diff --git a/src/blenderbim/docs/devs/georeferencing.rst b/src/blenderbim/docs/devs/georeferencing.rst deleted file mode 100644 index 500c08bff5..0000000000 --- a/src/blenderbim/docs/devs/georeferencing.rst +++ /dev/null @@ -1,95 +0,0 @@ -Georeferencing -============== - -In the AEC industry, works in the built environment are split between vertical -construction (such as buildings and sites), and horizontal construction (such as -transit, transmission, and subterranean networks). Blender and the BlenderBIM -Add-on is only suitable for vertical construction. - -IFC4 onwards supports georeferencing. The BlenderBIM Add-on has full support for -IFC georeferencing. Here are the potential scenarios you will encounter in the -wild for vertical construction. - -1. Correctly georeferenced IFC4 with a map conversion transformation -2. Correctly georeferenced IFC4 with a map conversion without a transformation -3. Non-georeferenced IFC4 -4. Non-georeferenced IFC2X3 - -The first scenario is desired for most disciplines, such as architects and all -engineers (except for civil). Typically, this results in small local engineering -coordinates, which work well in Blender. - -Correct georeferencing requires a projected CRS and a map conversion. -Unfortunately, many users may be under the impression that their file is -correctly georeferenced, but this is rarely the case. You can check whether your -file is correctly georeferenced in the ``IFC Georeferencing`` scene panel. If -you see "Not Georeferenced", your file is not correctly georeferenced. If your -file is georeferenced, it is still no guarantee that the georeferencing data is -actually correct, but how to determine this is out of scope of this article. - -For scenarios 2, 3, and 4, coordinates may be quite large. To present this data -in Blender, the BlenderBIM Add-on will automatically attempt to create a false -origin to preserve the precision of the model. The first coordinate greater than -1km will be detected and used as an offset coordinate. You can see the false -origin, if any, in the ``Blender Offset`` section of the ``IFC Georeferencing`` -scene panel. - -Instead of relying on an automatic false origin, you can also specify a custom -origin coordinate. To do this, choose ``Enable Advanced Mode`` when loading an -IFC project. Then enable the ``Import and Offset Model`` option and specify a -new coordinate to replace the origin's default of 0,0,0 in the ``Model Offset -Coordinates`` option. - -Dealing with large coordinates ------------------------------- - -In scenarios 2, 3, and 4, a BIM vendor will typically choose from two possible -methods to offset their coordinates into large map coordinates. - -The first method is to shift the origin point of objects in the model relative -to the global coordinate system. We call this the ``OBJECT_PLACEMENT`` method. -The second method is to shift the coordinates of geometry within the objects -themselves relative to the object placement. We call this the -``CARTESIAN_POINT`` method. Sometimes, BIM applications combine both of these -methods in a single IFC project. To see which workaround was used on an object, -check the "Blender Offset" property in the ``Transform`` object panel. - -Sometimes, a model shifts their coordinates for some objects, but not all. For -example, the walls in a model may have their object placement or cartesian -points shifted to map coordinates, however, the object placement of the site is -still at 0, 0, 0. Since these coordinates are so far apart, this creates a -problem, because Blender needs to choose between displaying the walls accurately -and sacrificing precision at the site placement, or vice versa, but it is -impossible to satisfy both simultaneously in the same Blender session. - -Many IFC viewers only show geometry, and don't show object placements. This may -give users the false impression that their coordinates in their IFC project do -not have such a large range. However, because the BlenderBIM Add-on is a full -authoring platform, we do need to show these placements and thus it is the users -responsibility to reconcile this inconsistency in their coordinates. Either the -user needs to fix their file to consistently offset all coordinates, or the user -needs to manually tell the BlenderBIM Add-on the coordinates of the desired -false origin. In the absence of manual intervention, the BlenderBIM Add-on will -make an intelligent guess, but it may be wrong. - -Coordinates and precision limits --------------------------------- - -Blender, and subsequently the BlenderBIM Add-on, is not designed for map -coordinate systems. Blender internally uses single precision floating point -calculations. A full description of the precision implications are described in -the `Blender working limits documentation -`__. - -From a software perspective, lengths greater than 5,000 meters start to -accumulate precision errors that affect the nearest millimeter. Therefore, from -a software perspective, it is unwise to embark on a project with coordinates -ranging greater than +/- 5km. - -However, if working in local engineering coordinates, a single transformation is -required to convert from local engineering coordinates to map coordinates. This -transformation includes a scale factor. The scale factor is only assumed to be -constant for small sites (defined approximately as less than 1km square). This -practical limit of georeferenced vertical construction is smaller than the -software limit, so this surveying convention is the actual limiting factor, not -the software. diff --git a/src/blenderbim/docs/index.rst b/src/blenderbim/docs/index.rst index 88e887f908..26d4afd10d 100644 --- a/src/blenderbim/docs/index.rst +++ b/src/blenderbim/docs/index.rst @@ -16,6 +16,7 @@ The BlenderBIM Add-on lets you analyse, create, and modify OpenBIM with Blender. users/installation users/exploring_an_ifc_model users/creating_your_first_ifc + users/georeferencing .. toctree:: :hidden: @@ -28,4 +29,3 @@ The BlenderBIM Add-on lets you analyse, create, and modify OpenBIM with Blender. devs/writing_docs devs/undo_system devs/ux_guidelines - devs/georeferencing diff --git a/src/blenderbim/docs/users/blenderoffset.png b/src/blenderbim/docs/users/blenderoffset.png new file mode 100644 index 0000000000..d307ab8bd6 Binary files /dev/null and b/src/blenderbim/docs/users/blenderoffset.png differ diff --git a/src/blenderbim/docs/users/coordinateconversion.png b/src/blenderbim/docs/users/coordinateconversion.png new file mode 100644 index 0000000000..838859f5c4 Binary files /dev/null and b/src/blenderbim/docs/users/coordinateconversion.png differ diff --git a/src/blenderbim/docs/users/georeferencing.rst b/src/blenderbim/docs/users/georeferencing.rst new file mode 100644 index 0000000000..f35e4697a8 --- /dev/null +++ b/src/blenderbim/docs/users/georeferencing.rst @@ -0,0 +1,243 @@ +Georeferencing +============== + +There are two types of construction: vertical construction (such as buildings +and sites) which deal with small distances typically under 1km, and horizontal +construction (such as transport, transmission, and subterranean networks) where +distances frequently exceed 1km. Blender and the BlenderBIM Add-on focuses on +vertical construction, and will typically just work out of the box. + +Coordinate reference systems +---------------------------- + +The minimum requirement for a georeferenced model is to specify the coordinate +reference system used. This is known as the **Projected CRS**, and is a feature +available in IFC4 onwards. + +.. warning:: + + IFC2X3 models cannot be georeferenced. There is a proposed convention to + provide fallback support but this is not supported yet in any known vendor. + Please consider upgrading to IFC4. + +Most architects and engineers will know the name of the **Projected CRS** +typically chosen by the surveyor. For example in Sydney, Australia, you might +use GDA2020 / MGA Zone 56. In IFC a standardised code from the EPSG public +registry is used to refer to the **Projected CRS**. For example, GDA 2020 / MGA +Zone 56 will be named EPSG:7856. + +You can check whether or not your model is georeferenced in the **IFC +Georeferencing** panel in the **Scene Properties** tab. You should see a section +for the **Projected CRS** with an EPSG code. + +.. image:: projectedcrs.png + +If you do not see this, your project is not georeferenced. + +.. Note:: + + Even if a model has large "real world coordinates", this does not mean the + project is georeferenced. Without a **Projected CRS**, these coordinates are + meaningless. + +Map conversions +--------------- + +The coordinates for the nominated **Projected CRS** are known as **Map +Coordinates**. These **Map Coordinates** are typically large numbers and read as +Eastings and Northings. + +In vertical construction, some disciplines (such as a civil engineer or +surveyor) will directly use **Map Coordinates** in their designs. Most others, +such as the architect, structural, and service engineers will instead use +**Local engineering coordinates**. A **Map Conversion** stores the parameters +for transforming **Local engineering coordinates** to **Map Coordinates**. + +For example, a civil engineer will work directly in **Map Coordinates**. This +means that the model's coordinates correlate directly to Eastings and +Northings. Similarly, the model's +Y axis will point to **Grid North**. As +there is no **Map Conversion** involved, you will see a 0 in the Eastings, +Northings, and Orthogonal Height in the **IFC Georeferencing** panel. + +.. image:: mapcoordinates.png + +When **Local engineering coordinates** are used, typically the architect will +nominate a local origin and model geometry will be drawn orthogonally (i.e. +along the X and Y axis). This local origin often correlates with a site bounary, +surveyed point, or grid intersection. This means that the model's coordinates +are typically smaller numbers and correlate to surface distance measurements, +not Eastings and Northings, and the model's +Y axis will point to **Project +North**. The surveyor will then provide the necessary **Map Conversion** +parameters to convert from **Local engineering coordinates** to Eastings, +Northings, Orthogonal Height, and **Grid North**. + +.. image:: mapconversion.png + +.. warning:: + + Coordinate systems are a technical topic. A common error is that disciplines + may choose to use **Map Coordinates** without realising that map distances + do not correlate with surface distances measured on the ground. Unless you + are trained to work in **Map Coordinates**, it is safer to work with local + engineering coordinates and consult your surveyor for professional guidance. + +**Map Conversions** contain three types of parameters. The **Eastings**, +**Northings** and **Orthogonal Height** parameters define the translation from +the model's XYZ coordinates to map Eastings, Northings, and Heights. The **X +Axis Abcissa** and **X Axis Ordinate** define the rotation vector from **Project +North** to **Grid North**. The **Scale** defines the average combined scale +factor across the small 1km site that converts from the model's surface +distances to map grid distances. Note that the **Scale** is actually not a +constant. However, for the small sites dealt with in vertical construction, it +may be approximated to be a constant by your surveyor and will typically be a +value close to, but not exactly 1. Your model's local engineering origin at 0, +0, 0, will always convert exactly to the **Easting**, **Northing**, and +**Orthogonal Height** displayed in this panel. + +.. tip:: + + The rotation from **Project North** to **Grid North** are shown using the **X + Axis Abcissa** and **X Axis Ordinate**. It sounds strange, but these two + numbers combine into a coordinate vector pointing along the X axis (i.e. + East). For example, an abscissa of 1 and an ordinate of 0 gives the vector of + (1, 0), which points directly in the +X direction, due East. This vector + means there is no rotation between **Project North** to **Grid North**. To + save you the mental struggle of converting this vector to degrees, a + calculated rotation is always just below these values. Phew! + +Working with Map Coordinates +---------------------------- + +The BlenderBIM Add-on is designed to work with small coordinates (under 1km), +whereas map coordinates are typically large. When you load an IFC which uses map +coordinates directly, or when you are working with IFC2X3 and you cannot use a +map conversion, the BlenderBIM Add-on will autodetect a point on your model to +use as a false origin. + +The XYZ offset used for the false origin will be shown in the **IFC +Georeferencing** panel under the **Blender Offset** header. It +is very similar to a **Map Conversion**, but it will not have a scale and only +temporarily affects your Blender session. + +.. image:: blenderoffset.png + +.. note:: + + A Blender offset is simply a shift in coordinates to reduce large model + coordinates to smaller coordinates. It should not be used as an indicator of + whether georeferencing is done correctly. Always check the **Projected + CRS**, **Map Conversion** and confirm the parameters with your surveyor. + +This distance limit of 1km and autodetected false origin may not be appropriate +for your project. For example, your project may exceed the 1km limit, or you may +want to federate multiple files together and manually specify a consistent and +fixed false origin. You can customise these options by choosing **Enable +Advanced Mode** when loading a project. Then, set the **Distance Limit** (in +meters) and the **False Origin** coordinate before pressing **Load Project +Elements**. + +.. image:: manualorigin.png + +When a false origin is used, there are two possible methods to offset objects by +the false origin. + +The first method is to offset the origin point of objects. We call this the +**Object Placement** method. The second method is to offset the local +coordinates of geometry within the objects themselves. We call this the +**Cartesian Point** method. Sometimes, BIM applications combine both of these +methods in a single IFC project. To see which workaround was used on an object, +check the "Blender Offset" property in the **Transform** panel in the **Object +Properties**. This is an advanced property used by powerusers to debug +coordinate issues and may be safely ignored by most users. + +.. image:: offsetmode.png + +Incorrect coordinate use +------------------------ + +Sometimes, a model may mix **Map Coordinates** and **Local engineering +coordinates**. For example, a surveyed pipe may have its placement use **Map +Coordinates** with large Eastings and Northings. However, the placement of the +site object may be still set at 0, 0, 0. Since this range of coordinates exceed +the default 1km distance limit, this creates a problem. Blender needs to choose +between displaying the pipe accurately and sacrificing precision at the site +placement, or vice versa, but it is impossible to satisfy both simultaneously in +the same Blender session. + +.. warning:: + + Many IFC viewers only show geometry, and don't show object placements. This may + give users the false impression that their coordinates in their IFC project + do not have such a large range. However, as a native IFC authoring platform, + the BlenderBIM Add-on will not accept this inconsistency. + +At this point, it is the users responsibility to reconcile this inconsistency in +their coordinates. Either the user needs to fix their file to consistently +offset all coordinates, or the user needs to manually tell the BlenderBIM Add-on +the coordinates of the desired false origin and accept the precision loss. + +Converting local and map coordinates +------------------------------------ + +You can convert **Local engineering coordinates** to **Map coordinates** and +vice versa in the **Viewport** panel. First, enable ``View > Sidebar`` then type +in your coordinate in the **Input** field. Press either the **Local to Global** +or **Global to Local** button to convert the coordinate. You will see the result +of the calculation in the **Output** field. + +.. image:: coordinateconversion.png + +True north +---------- + +When **Local engineering coordinates** are used, the model's +Y axis points to +**Project North** for the convenience of drafting. When **Map Coordinates** are +used, the model's +Y axis points to **Grid North** for the neccessity of +surveying. + +**Project North** and **Grid North** is different to **True North**. The angle +to **True North** is not a fixed angle. It will actually vary depending on the +Eastings and Northings you choose to calculate it from. + +However, this variable **True North** is a great source of confusion to +architects, who typically just want to do a shadow study, solar study, or +similar and go out for an early lunch. IFC can store a fixed **True North** +value as a reference to be used for these types of usecases. If one is stored in +your project, you may see it under the **True North** section of the **IFC +Georeferencing** panel. Your surveyor will be able to provide the **True North** +vector, but it should be only used as a reference, never used as a way to +coordinate model rotations, and always with the understanding that it is not a +fixed value. + +.. image:: truenorth.png + +.. warning:: + + Fun fact: **Magnetic North** is useless for the purposes of construction. + +Coordinate precision limits +--------------------------- + +The BlenderBIM Add-on focuses on vertical construction. Vertical construction +typically uses **Local engineering coordinates** on a small site. The +buildingSMART georeferencing technical experts panel have determined that a +small site under 1km square can be assumed to have a constant **Map +Conversion**. + +Therefore, if your model is less than 1km square, you are within the coordinate +precision limits. This is where the 1km default distance limit is derived from. + +If you want to exceed the 1km square surveying limitation, you will need to be +aware of software limitations that can result in precision loss when large +coordinate ranges are used. + +Blender, and subsequently the BlenderBIM Add-on, is not designed for **Map +Coordinates**. Blender internally uses single precision floating point +calculations. A full description of the precision implications are described in +the `Blender working limits documentation +`__. + +This means that lengths greater than 5,000 meters start to accumulate software +precision errors that affect the nearest millimeter. Therefore, from a software +perspective, it is unwise to embark on a project with coordinates ranging +greater than +/- 5km. diff --git a/src/blenderbim/docs/users/manualorigin.png b/src/blenderbim/docs/users/manualorigin.png new file mode 100644 index 0000000000..ba769b7bd0 Binary files /dev/null and b/src/blenderbim/docs/users/manualorigin.png differ diff --git a/src/blenderbim/docs/users/mapconversion.png b/src/blenderbim/docs/users/mapconversion.png new file mode 100644 index 0000000000..7d2aed8c0b Binary files /dev/null and b/src/blenderbim/docs/users/mapconversion.png differ diff --git a/src/blenderbim/docs/users/mapcoordinates.png b/src/blenderbim/docs/users/mapcoordinates.png new file mode 100644 index 0000000000..b69be329d7 Binary files /dev/null and b/src/blenderbim/docs/users/mapcoordinates.png differ diff --git a/src/blenderbim/docs/users/offsetmode.png b/src/blenderbim/docs/users/offsetmode.png new file mode 100644 index 0000000000..3731df4383 Binary files /dev/null and b/src/blenderbim/docs/users/offsetmode.png differ diff --git a/src/blenderbim/docs/users/projectedcrs.png b/src/blenderbim/docs/users/projectedcrs.png new file mode 100644 index 0000000000..1997bf51ff Binary files /dev/null and b/src/blenderbim/docs/users/projectedcrs.png differ diff --git a/src/blenderbim/docs/users/truenorth.png b/src/blenderbim/docs/users/truenorth.png new file mode 100644 index 0000000000..a1700b5946 Binary files /dev/null and b/src/blenderbim/docs/users/truenorth.png differ