Write documentation for georeferencing

src/blenderbim/docs/devs/georeferencing.rst

@@ -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
-<https://docs.blender.org/manual/en/latest/advanced/limits.html>`__.
-
-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.

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

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
+<https://docs.blender.org/manual/en/latest/advanced/limits.html>`__.
+
+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.