`ifcopenshell.api.georeference`¶

Manage georeferencing metadata

IFC model geometry may have a coordinate reference system (CRS) assigned to it. It may also optionally have a map conversion defined to transform to and from map coordinates and project local engineering coordinates.

Submodules¶

Package Contents¶

ifcopenshell.api.georeference.add_georeferencing(file: ifcopenshell.file, ifc_class: str = 'IfcMapConversion', name: str = 'EPSG:3857') → None¶

Add empty georeferencing entities to a model

By default, models are not georeferenced. Georeferencing requires two entities: a definition of the projected coordinated reference system (CRS) used, and the transformation parameters between any local coordinate system and that projected CRS if any.

This function will create the entities to store the projected CRS and map conversion transformation, but will leave all the parameters blank. It is this the users responsibility to specify the correct georeferencing parameters. See ifcopenshell.api.georeference.edit_georeferencing.

Parameters:: ifc_class – A type of IfcCoordinateOperation. For IFC2X3, this has no impact and only uses ePSet_MapConversion.

Example:

ifcopenshell.api.georeference.add_georeferencing(model)

ifcopenshell.api.georeference.edit_georeferencing(file: ifcopenshell.file, coordinate_operation: dict[str, Any] | None = None, projected_crs: dict[str, Any] | None = None) → None¶

Edits the attributes of a map conversion, projected CRS, and true north

Setting the correct georeferencing parameters is a complex topic and should ideally be done with three parties present: the lead architect, surveyor, and a third-party digital engineer with expertise in IFC to moderate. For more information, read the Bonsai documentation for Georeferencing: https://docs.bonsaibim.org/users/advanced/georeferencing.html

For more information about the attributes and data types of an IfcCoordinateOperation, consult the IFC documentation.

For more information about the attributes and data types of an IfcProjectedCRS, consult the IFC documentation.

See ifcopenshell.util.geolocation for more utilities to convert to and from local and map coordinates to check your results.

Parameters:

coordinate_operation – The dictionary of attribute names and values you want to edit.
projected_crs – The IfcProjectedCRS dictionary of attribute names and values you want to edit.

Example:

ifcopenshell.api.georeference.add_georeferencing(model)
# This is the simplest scenario, a defined CRS (GDA2020 / MGA Zone
# 56, typically used in Sydney, Australia) but with no local
# coordinates. This is only recommended for horizontal construction
# projects, not for vertical construction (such as buildings).
ifcopenshell.api.georeference.edit_georeferencing(model,
    projected_crs={"Name": "EPSG:7856"})

# For buildings, it is almost always recommended to specify map
# conversion parameters to a false origin and orientation to project
# north. See the diagram in the Bonsai Georeferencing
# documentation for correct calculation of the X Axis Abcissa and
# Ordinate.
ifcopenshell.api.georeference.edit_georeferencing(model,
    projected_crs={"Name": "EPSG:7856"},
    coordinate_operation={
        "Eastings": 335087.17, # The architect nominates a false origin
        "Northings": 6251635.41, # The architect nominates a false origin
        # Note: this is the angle difference between Project North
        # and Grid North. Remember: True North should never be used!
        "XAxisAbscissa": cos(radians(-30)), # The architect nominates a project north
        "XAxisOrdinate": sin(radians(-30)), # The architect nominates a project north
        "Scale": 0.99956, # Ask your surveyor for your site's average combined scale factor!
    })

ifcopenshell.api.georeference.edit_true_north(file: ifcopenshell.file, true_north: tuple[float, float] | float | None = 0.0) → None¶

Edits the true north

Given project north being up (i.e. a vector of 0, 1), true north is defined as a unitised 2D vector pointing to true north. Alternatively, true north may be defined as a rotation from project north to true north. Anticlockwise is positive.

Note that true north is not part of georeferencing, and is only optionally provided as a reference value, typically for solar analysis. Remember: grid north (what your surveyor will typically use) is not the same as true north!

Parameters:: true_north – A unitised 2D vector, where each ordinate is a float, or an angle in decimal degrees where anticlockwise is positive.

Example:

# Both of these are identical, and indicate that:
# - If project north is up the page, true north is in the top left
# - The building is therefore facing north east
ifcopenshell.api.georeference.edit_true_north(model, true_north=30)
ifcopenshell.api.georeference.edit_true_north(model, true_north=(-0.5, 0.8660254))

# This unsets true north
ifcopenshell.api.georeference.edit_true_north(model, true_north=None)

ifcopenshell.api.georeference.edit_wcs(file: ifcopenshell.file, x: float = 0.0, y: float = 0.0, z: float = 0.0, rotation: float = 0.0, is_si: bool = True) → None¶

Edits the WCS for all geometric contexts to a translation and rotation

Typically, a project’s local engineering origin (0, 0, 0) has a coordinate operation (e.g. map conversion) to a projected CRS. If a WCS is provided, the coordinate operation is relative to the WCS, not the local engineering origin.

For example, if I have an IfcSite with a placement at (10, 0, 0) and a map conversion of (50, 0, 0), my IfcSite’s local XYZ is at (10, 0, 0) with an ENH (Easting, Northing, Height) of (60, 0, 0).

If I then define by WCS at (15, 0, 0), my IfcSite’s local XYZ is still at (10, 0, 0) but its ENH is now at (45, 0, 0).

It’s recommended to leave the WCS at 0,0,0. Please :)

Parameters:

x – The X translation of the WCS
y – The Y translation of the WCS
z – The Z translation of the WCS
rotation – The rotation around the Z axis (i.e. top down plan view) in decimal degrees of the WCS. Anticlockwise is positive.

Example:

# This is the simplest scenario, resetting the WCS to 0,0,0 with no rotation (recommended)
ifcopenshell.api.georeference.edit_wcs(model)

ifcopenshell.api.georeference.remove_georeferencing(file: ifcopenshell.file) → None¶

Remove georeferencing data

All georeferencing parameters such as projected CRS and map conversion data will be lost.

In IFC2X3, the psets will be removed from the IfcProject.

Example:

ifcopenshell.api.georeference.add_georeferencing(model) # Let’s change our mind ifcopenshell.api.georeference.remove_georeferencing(model)

ifcopenshell.api.georeference¶

Submodules¶

Package Contents¶

`ifcopenshell.api.georeference`¶