ifcopenshell.util.geolocation

Module Contents

ifcopenshell.util.geolocation.angle2xaxis(angle)

Converts an angle into an X axis abscissa and ordinate

The inverse of xaxis2angle.

Parameters:

angle (float) – The angle in decimal degrees where anticlockwise is positive.

Returns:

A tuple of X axis abscissa and ordinate

Return type:

tuple[float]

ifcopenshell.util.geolocation.angle2yaxis(angle)

Converts an angle into an Y axis abscissa and ordinate

The inverse of yaxis2angle.

Parameters:

angle (float) – The angle in decimal degrees where anticlockwise is positive.

Returns:

A tuple of Y axis abscissa and ordinate

Return type:

tuple[float]

ifcopenshell.util.geolocation.auto_enh2xyz(ifc_file, easting, northing, height)

Convert from global map coordinate eastings, northings, and heights to local XYZ coordinates

The necessary georeferencing map conversion is automatically detected from the IFC map conversion parameters present in the IFC model. If no map conversion is present, then the Z coordinate is returned unchanged.

For IFC2X3, the map conversion is detected from the IfcProject’s ePSet_MapConversion. See the “User Guide for Geo-referencing in IFC”: https://www.buildingsmart.org/standards/bsi-standards/standards-library/

Parameters:

  • ifc_file (ifcopenshell.file) – The IFC file

  • easting (float) – The global easting map coordinate provided in map units.

  • northing (float) – The global northing map coordinate provided in map units.

  • height (float) – The global height map coordinate provided in map units.

Returns:

The local engineering XYZ coordinates in project length units.

Return type:

tuple[float]

ifcopenshell.util.geolocation.auto_xyz2enh(ifc_file, x, y, z)

Convert from local XYZ coordinates to global map coordinate eastings, northings, and heights

The necessary georeferencing map conversion is automatically detected from the IFC map conversion parameters present in the IFC model. If no map conversion is present, then the Z coordinate is returned unchanged.

For IFC2X3, the map conversion is detected from the IfcProject’s ePSet_MapConversion. See the “User Guide for Geo-referencing in IFC”: https://www.buildingsmart.org/standards/bsi-standards/standards-library/

Parameters:

  • ifc_file (ifcopenshell.file) – The IFC file

  • x (float) – The X local engineering coordinate provided in project length units.

  • y (float) – The Y local engineering coordinate provided in project length units.

  • z (float) – The Z local engineering coordinate provided in project length units.

Returns:

The global map coordinate eastings, northings, and height in map units.

Return type:

tuple[float]

ifcopenshell.util.geolocation.auto_z2e(ifc_file, z)

Convert a Z coordinate to an elevation using model georeferencing data

The necessary georeferencing map conversion is automatically detected from the IFC map conversion parameters present in the IFC model. If no map conversion is present, then the Z coordinate is returned unchanged.

For IFC2X3, the map conversion is detected from the IfcProject’s ePSet_MapConversion. See the “User Guide for Geo-referencing in IFC”: https://www.buildingsmart.org/standards/bsi-standards/standards-library/

Parameters:

  • ifc_file (ifcopenshell.file) – The IFC file

  • z (float) – The Z local engineering coordinate provided in project length units.

Returns:

The elevation in project length units.

Return type:

float

ifcopenshell.util.geolocation.dd2dms(dd, use_ms=False)

Convert decimal degrees to degrees, minutes, and (milli)seconds format

Parameters:

  • dd (float) – The decimal degrees

  • use_ms (bool) – True if to include milliseconds and false otherwise. Defaults to false.

Returns:

The angle in a tuple of either 3 or 4 values, being degrees, minutes, seconds, and optionally milliseconds.

Return type:

tuple[float]

ifcopenshell.util.geolocation.dms2dd(degrees, minutes, seconds, ms=0)

Convert degrees, minutes, and (milli)seconds to decimal degrees

Parameters:

  • degrees (int) – The degrees component

  • minutes (int) – The minutes component

  • seconds (int) – The seconds component

  • ms (int) – The milliseconds component

Returns:

The angle in decimal degrees.

Return type:

float

ifcopenshell.util.geolocation.enh2xyz(e, n, h, eastings, northings, orthogonal_height, x_axis_abscissa, x_axis_ordinate, scale=None)

Manually convert map eastings, northings, and height to local XYZ coordinates

This function is for advanced users as it allows you to specify your own helmert transformation parameters (i.e. those typically stored in IfcMapConversion). This manual approach is useful for tests or in case your are setting your helmert transformations in non-standard locations, or if you are applying your own temporary false origin (such as when federating models for digital twins of large cities).

No unit conversion is performed.

For most scenarios you should use auto_enh2xyz instead.

Parameters:

  • e (float) – The global easting map coordinate.

  • n (float) – The global northing map coordinate.

  • h (float) – The global height map coordinate.

  • eastings (float) – The eastings offset to apply.

  • northings (float) – The northings offset to apply.

  • orthogonal_height (float) – The orthogonal height offset to apply.

  • x_axis_abscissa (float) – The X axis abscissa (i.e. first coordinate) of the 2D vector that points to the local X axis when in map coordinates.

  • x_axis_ordinate (float) – The X axis ordinate (i.e. second coordinate) of the 2D vector that points to the local X axis when in map coordinates.

  • scale (float) – The combined scale factor to convert from local coordinates to map coordinates.

Returns:

A tuple of three ordinates representing XYZ.

Return type:

tuple[float]

ifcopenshell.util.geolocation.get_grid_north(ifc_file)

Get an angle pointing to map grid north

Anticlockwise is positive.

The necessary georeferencing map conversion is automatically detected from the IFC map conversion parameters present in the IFC model. If no map conversion is present, then the Z coordinate is returned unchanged.

For IFC2X3, the map conversion is detected from the IfcProject’s ePSet_MapConversion. See the “User Guide for Geo-referencing in IFC”: https://www.buildingsmart.org/standards/bsi-standards/standards-library/

Parameters:

ifc_file (ifcopenshell.file) – The IFC file

Returns:

An angle to grid north in decimal degrees

Return type:

float

ifcopenshell.util.geolocation.get_true_north(ifc_file)

Get an angle pointing to global true north

Anticlockwise is positive.

Always remember that true north is not a constant! (Unless you are working in polar coordinates) This true north is only a reference value useful for things like solar analysis on small sites (<1km). If you’re after the north that your surveyor is using, you’re probably after get_grid_north instead.

Parameters:

ifc_file (ifcopenshell.file) – The IFC file

Returns:

An angle to true north in decimal degrees

Return type:

float

ifcopenshell.util.geolocation.global2local(matrix, eastings, northings, orthogonal_height, x_axis_abscissa, x_axis_ordinate, scale=None)

Manually convert a 4x4 matrix from global to local coordinates

This function is for advanced users as it allows you to specify your own helmert transformation parameters (i.e. those typically stored in IfcMapConversion). This manual approach is useful for tests or in case your are setting your helmert transformations in non-standard locations, or if you are applying your own temporary false origin (such as when federating models for digital twins of large cities).

No unit conversion is performed.

Parameters:

  • matrix (np.array) – A 4x4 numpy matrix representing global coordinates.

  • eastings (float) – The eastings offset to apply.

  • northings (float) – The northings offset to apply.

  • orthogonal_height (float) – The orthogonal height offset to apply.

  • x_axis_abscissa (float) – The X axis abscissa (i.e. first coordinate) of the 2D vector that points to the local X axis when in map coordinates.

  • x_axis_ordinate (float) – The X axis ordinate (i.e. second coordinate) of the 2D vector that points to the local X axis when in map coordinates.

  • scale (float) – The combined scale factor to convert from local coordinates to map coordinates.

Returns:

A numpy 4x4 array matrix representing local coordinates.

Return type:

np.array

ifcopenshell.util.geolocation.local2global(matrix, eastings, northings, orthogonal_height, x_axis_abscissa, x_axis_ordinate, scale=None)

Manually convert a 4x4 matrix from local to global coordinates

This function is for advanced users as it allows you to specify your own helmert transformation parameters (i.e. those typically stored in IfcMapConversion). This manual approach is useful for tests or in case your are setting your helmert transformations in non-standard locations, or if you are applying your own temporary false origin (such as when federating models for digital twins of large cities).

No unit conversion is performed.

Parameters:

  • matrix (np.array) – A 4x4 numpy matrix representing local coordinates.

  • eastings (float) – The eastings offset to apply.

  • northings (float) – The northings offset to apply.

  • orthogonal_height (float) – The orthogonal height offset to apply.

  • x_axis_abscissa (float) – The X axis abscissa (i.e. first coordinate) of the 2D vector that points to the local X axis when in map coordinates.

  • x_axis_ordinate (float) – The X axis ordinate (i.e. second coordinate) of the 2D vector that points to the local X axis when in map coordinates.

  • scale (float) – The combined scale factor to convert from local coordinates to map coordinates.

Returns:

A numpy 4x4 array matrix representing global coordinates.

Return type:

np.array

ifcopenshell.util.geolocation.local2global_ifc4x3(matrix, eastings, northings, orthogonal_height, x_axis_abscissa, x_axis_ordinate, scale=1.0, factor_x=1.0, factor_y=1.0, factor_z=1.0)
ifcopenshell.util.geolocation.xaxis2angle(x, y)

Converts X axis abscissa and ordinates to an angle in decimal degrees

Parameters:

  • x (float) – The X axis abscissa

  • y (float) – The X axis ordinate

Returns:

The equivalent angle in decimal degrees from the X axis

Return type:

float

ifcopenshell.util.geolocation.xyz2enh(x, y, z, eastings, northings, orthogonal_height, x_axis_abscissa, x_axis_ordinate, scale=None)

Manually convert local XYZ coordinates to map eastings, northings, and height

This function is for advanced users as it allows you to specify your own helmert transformation parameters (i.e. those typically stored in IfcMapConversion). This manual approach is useful for tests or in case your are setting your helmert transformations in non-standard locations, or if you are applying your own temporary false origin (such as when federating models for digital twins of large cities).

No unit conversion is performed.

For most scenarios you should use auto_xyz2enh instead.

Parameters:

  • x (float) – The X local engineering coordinate.

  • y (float) – The Y local engineering coordinate.

  • z (float) – The Z local engineering coordinate.

  • eastings (float) – The eastings offset to apply.

  • northings (float) – The northings offset to apply.

  • orthogonal_height (float) – The orthogonal height offset to apply.

  • x_axis_abscissa (float) – The X axis abscissa (i.e. first coordinate) of the 2D vector that points to the local X axis when in map coordinates.

  • x_axis_ordinate (float) – The X axis ordinate (i.e. second coordinate) of the 2D vector that points to the local X axis when in map coordinates.

  • scale (float) – The combined scale factor to convert from local coordinates to map coordinates.

Returns:

A tuple of three ordinates representing the easting, northing and height.

Return type:

tuple[float]

ifcopenshell.util.geolocation.xyz2enh_ifc4x3(x, y, z, eastings, northings, orthogonal_height, x_axis_abscissa, x_axis_ordinate, scale=1.0, factor_x=1.0, factor_y=1.0, factor_z=1.0)
ifcopenshell.util.geolocation.yaxis2angle(x, y)

Converts Y axis abscissa and ordinates to an angle in decimal degrees

The Y axis abscissa and ordinate is how IFC stores true north.

Parameters:

  • x (float) – The Y axis abscissa

  • y (float) – The Y axis ordinate

Returns:

The equivalent angle in decimal degrees from the Y axis

Return type:

float

ifcopenshell.util.geolocation.z2e(z, h)

Manually convert a Z coordinate to an elevation

This function is for advanced users as it allows you to specify your own orthogonal height offset.

For most scenarios you should use auto_z2e instead.

Parameters:

  • z (float) – The Z local engineering coordinate provided in project length units.

  • h (float) – The orthogonal height offset in project length units.

Returns:

The elevation in project length units.

Return type:

float