ifcopenshell.util.geolocation

Module Contents

class ifcopenshell.util.geolocation.HelmertTransformation

Bases: NamedTuple

e: float
factor_x: float
factor_y: float
factor_z: float
h: float
n: float
scale: float
xaa: float
xao: float
ifcopenshell.util.geolocation.angle2xaxis(angle: float) → tuple[float, float]

Converts an angle into an X axis abscissa and ordinate

The inverse of xaxis2angle().

Parameters:

angle – The angle in decimal degrees where anticlockwise is positive.

Returns:

A tuple of X axis abscissa and ordinate

ifcopenshell.util.geolocation.angle2yaxis(angle: float) → tuple[float, float]

Converts an angle into an Y axis abscissa and ordinate

The inverse of yaxis2angle().

Parameters:

angle – The angle in decimal degrees where anticlockwise is positive.

Returns:

A tuple of Y axis abscissa and ordinate

ifcopenshell.util.geolocation.auto_enh2xyz(ifc_file, easting, northing, height, is_specified_in_map_units: bool = True)

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 – The IFC file

  • easting – The global easting map coordinate provided in map units.

  • northing – The global northing map coordinate provided in map units.

  • height – The global height map coordinate provided in map units.

  • is_specified_in_map_units – True if the input eastings, northing, and height are in map units.

Returns:

The local engineering XYZ coordinates in project length units.

ifcopenshell.util.geolocation.auto_global2local(ifc_file: ifcopenshell.file, matrix: numpy.typing.NDArray[numpy.float64], is_specified_in_map_units: bool = True) → numpy.typing.NDArray[numpy.float64]

Convert a global map matrix to a local matrix

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 matrix is returned unchanged.

Parameters:

  • ifc_file – The IFC file

  • matrix – A 4x4 numpy matrix representing local coordinates.

  • should_return_in_map_units – If true, the result is given in map units. If false, the result will be converted back into project units.

  • is_specified_in_map_units – True if the input matrix is in map units.

Returns:

A numpy 4x4 array matrix representing global coordinates.

ifcopenshell.util.geolocation.auto_local2global(ifc_file: ifcopenshell.file, matrix: numpy.typing.NDArray[numpy.float64], should_return_in_map_units: bool = True) → numpy.typing.NDArray[numpy.float64]

Convert a local matrix to a global map matrix

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 matrix is returned unchanged.

Parameters:

  • ifc_file – The IFC file

  • matrix – A 4x4 numpy matrix representing local coordinates.

  • should_return_in_map_units – If true, the result is given in map units. If false, the result will be converted back into project units.

Returns:

A numpy 4x4 array matrix representing global coordinates.

ifcopenshell.util.geolocation.auto_xyz2enh(ifc_file: ifcopenshell.file, x: float, y: float, z: float, should_return_in_map_units: bool = True) → tuple[float, float, float]

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 coordinates are 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 – The IFC file

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

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

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

  • should_return_in_map_units – If true, the result is given in map units. If false, the result will be converted back into project units.

Returns:

The global map coordinate eastings, northings, and height.

ifcopenshell.util.geolocation.auto_z2e(ifc_file: ifcopenshell.file, z: float, should_return_in_map_units: bool = True) → float

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 – The IFC file

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

Returns:

The elevation in project length units.

ifcopenshell.util.geolocation.dd2dms(dd: float, use_ms: bool = False) → tuple[float, float, float, float] | tuple[float, float, float]

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

Parameters:

  • dd – The decimal degrees

  • use_ms – 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.

ifcopenshell.util.geolocation.dms2dd(degrees: int, minutes: int, seconds: int, ms: int = 0) → float

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

Parameters:

  • degrees – The degrees component

  • minutes – The minutes component

  • seconds – The seconds component

  • ms – The milliseconds component

Returns:

The angle in decimal degrees.

ifcopenshell.util.geolocation.enh2xyz(e: float, n: float, h: float, eastings: float = 0.0, northings: float = 0.0, orthogonal_height: float = 0, x_axis_abscissa: float = 1.0, x_axis_ordinate: float = 0.0, scale: float = 1.0, factor_x: float = 1.0, factor_y: float = 1.0, factor_z: float = 1.0) → tuple[float, float, float]

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).

For most scenarios you should use auto_enh2xyz() instead.

Parameters:

  • e – The global easting map coordinate.

  • n – The global northing map coordinate.

  • h – The global height map coordinate.

  • eastings – The eastings offset to apply.

  • northings – The northings offset to apply.

  • orthogonal_height – The orthogonal height offset to apply.

  • x_axis_abscissa – 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 – The X axis ordinate (i.e. second coordinate) of the 2D vector that points to the local X axis when in map coordinates.

  • scale – The unit scale such that local ordinate * scale = map ordinate. E.g. if your project is in millimeters but your CRS is in meters, your scale should be 0.001.

  • factor_x – The combined scale factor for the X value to convert from local coordinates to map coordinates. Your surveyor will typically know this number and approximate it as a constant on a small site. Typically factor_x and factor_y will be identical, and factor_z will be 1.

  • factor_y – Same but for the Y value.

  • factor_z – Same but for the Z value.

Returns:

A tuple of three ordinates representing XYZ.

ifcopenshell.util.geolocation.get_grid_north(ifc_file: ifcopenshell.file) → float

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 – The IFC file

Returns:

An angle to grid north in decimal degrees

ifcopenshell.util.geolocation.get_helmert_transformation_parameters(ifc_file: ifcopenshell.file) → HelmertTransformation | None

Retrieves the parameters of a helmert transformation that represents a coordinate operation

This coordinate operation is typically what is used to convert between local engineering coordinates and map coordinates.

Parameters:

ifc_file – The IFC model, typically containing an IfcCoordinateOperation such as an IfcMapConversion.

Returns:

The parameters of the transformation.

ifcopenshell.util.geolocation.get_true_north(ifc_file: ifcopenshell.file) → float

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 – The IFC file

Returns:

An angle to true north in decimal degrees

ifcopenshell.util.geolocation.get_wcs(ifc_file: ifcopenshell.file) → numpy.typing.NDArray[numpy.float64] | None

Gets the WCS (prioritising 3D contexts) as a matrix

Param:

The IFC file

Returns:

A 4x4 matrix in project units

ifcopenshell.util.geolocation.global2local(matrix: numpy.typing.NDArray[numpy.float64], eastings: float = 0.0, northings: float = 0.0, orthogonal_height: float = 0.0, x_axis_abscissa: float = 1.0, x_axis_ordinate: float = 0.0, scale: float = 1.0, factor_x: float = 1.0, factor_y: float = 1.0, factor_z: float = 1.0) → numpy.typing.NDArray[numpy.float64]

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).

Parameters:

  • matrix – A 4x4 numpy matrix representing global coordinates.

  • eastings – The eastings offset to apply.

  • northings – The northings offset to apply.

  • orthogonal_height – The orthogonal height offset to apply.

  • x_axis_abscissa – 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 – The X axis ordinate (i.e. second coordinate) of the 2D vector that points to the local X axis when in map coordinates.

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

Returns:

A numpy 4x4 array matrix representing local coordinates.

ifcopenshell.util.geolocation.local2global(matrix: numpy.typing.NDArray[numpy.float64], eastings: float = 0.0, northings: float = 0.0, orthogonal_height: float = 0.0, x_axis_abscissa: float = 1.0, x_axis_ordinate: float = 0.0, scale: float = 1.0, factor_x: float = 1.0, factor_y: float = 1.0, factor_z: float = 1.0) → numpy.typing.NDArray[numpy.float64]

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).

For most scenarios you should use auto_local2global() instead.

Parameters:

  • matrix – A 4x4 numpy matrix representing local coordinates.

  • eastings – The eastings offset to apply.

  • northings – The northings offset to apply.

  • orthogonal_height – The orthogonal height offset to apply.

  • x_axis_abscissa – 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 – The X axis ordinate (i.e. second coordinate) of the 2D vector that points to the local X axis when in map coordinates.

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

Returns:

A numpy 4x4 array matrix representing global coordinates.

ifcopenshell.util.geolocation.xaxis2angle(x: float, y: float) → float

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

The X axis abscissa and ordinate is how IFC stores grid north.

This X axis vector indicates “where is project east, if grid north is up the page?”. See the diagram on the IfcGeometricRepresentationContext documentation for clarification.

The angle indicates “how do I rotate project east to get to grid east?”. Alternatively: “how do I rotate project north to get to grid north?”. Positive angles are anticlockwise.

Parameters:

  • x – The X axis abscissa

  • y – The X axis ordinate

Returns:

The equivalent angle in decimal degrees from the X axis

ifcopenshell.util.geolocation.xyz2enh(x: float, y: float, z: float, eastings: float = 0.0, northings: float = 0.0, orthogonal_height: float = 0.0, x_axis_abscissa: float = 1.0, x_axis_ordinate: float = 0.0, scale: float = 1.0, factor_x: float = 1.0, factor_y: float = 1.0, factor_z: float = 1.0) → tuple[float, float, float]

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).

For most scenarios you should use auto_xyz2enh() instead.

Parameters:

  • x – The X local engineering coordinate.

  • y – The Y local engineering coordinate.

  • z – The Z local engineering coordinate.

  • eastings – The eastings offset to apply.

  • northings – The northings offset to apply.

  • orthogonal_height – The orthogonal height offset to apply.

  • x_axis_abscissa – 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 – The X axis ordinate (i.e. second coordinate) of the 2D vector that points to the local X axis when in map coordinates.

  • scale – The unit scale such that local ordinate * scale = map ordinate. E.g. if your project is in millimeters but your CRS is in meters, your scale should be 0.001.

  • factor_x – The combined scale factor for the X value to convert from local coordinates to map coordinates. Your surveyor will typically know this number and approximate it as a constant on a small site. Typically factor_x and factor_y will be identical, and factor_z will be 1.

  • factor_y – Same but for the Y value.

  • factor_z – Same but for the Z value.

Returns:

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

ifcopenshell.util.geolocation.yaxis2angle(x: float, y: float) → float

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

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

This Y axis vector indicates “where is true north, if project north is up the page?”. See the diagram on the IfcGeometricRepresentationContext documentation for clarification.

The angle indicates “how do I rotate project north to get to true north?”. Positive angles are anticlockwise.

Parameters:

  • x – The Y axis abscissa

  • y – The Y axis ordinate

Returns:

The equivalent angle in decimal degrees from the Y axis

ifcopenshell.util.geolocation.z2e(z: float, orthogonal_height: float = 0.0, scale: float = 1.0, factor_z: float = 1.0) → float

Manually convert a Z coordinate to a map elevation

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

For most scenarios you should use auto_z2e() instead.

Parameters:

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

  • orthogonal_height – The orthogonal height offset to apply.

  • scale – The unit scale such that local ordinate * scale = map ordinate. E.g. if your project is in millimeters but your CRS is in meters, your scale should be 0.001.

  • factor_x – The combined scale factor for the Z value to convert from local coordinates to map coordinates. Your surveyor will typically know this number and approximate it as a constant on a small site. This is typically just 1.0, as average combined scale factors usually only affect the XY axes.

Returns:

The elevation in map units.