Improve georeferencing documentation

src/blenderbim/docs/blenderbim/georeferencing.rst

@@ -11,63 +11,66 @@ 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 without a map conversion transformation
+2. Correctly georeferenced IFC4 with a map conversion without a transformation
-3. Non-georeferenced georeferenced IFC4
+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).
+engineers (except for civil). Typically, this results in small local engineering
+coordinates, which work well in Blender.
 
-For scenarios 2, 3, and 4, the BlenderBIM Add-on will automatically attempt to
+Correct georeferencing requires a projected CRS and a map conversion.
-offset coordinates to preserve the precision of the model. The first coordinate
+Unfortunately, many users may be under the impression that their file is
-greater than 1km will be detected and used as an offset coordinate. It is
+correctly georeferenced, but this is rarely the case. You can check whether your
-possible to specify a custom offset coordinate.
+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.
 
-Non-georeferenced workarounds
+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.
 
-The unfortunate reality is that IFC2X3 does not support georeferencing, and most
+Instead of relying on an automatic false origin, you can also specify a custom
-vendors have poor and inconsistent support for georeferencing, even in IFC4.
+origin coordinate. To do this, choose ``Enable Advanced Mode`` when loading an
-Some users may be under the impression that their file is correctly
+IFC project.  Then enable the ``Import and Offset Model`` option and specify a
-georeferenced, but this is rarely the case. This creates problems. You can see
+new coordinate to replace the origin's default of 0,0,0 in the ``Model Offset
-whether your file is correctly georeferenced in the ``IFC Georeferencing``
+Coordinates`` option.
-scene panel. If you see "Not Georeferenced", your file is not correctly
-georeferenced. If your file is georeferenced, it is no guarantee that the
-georeferencing data is actually correct, but how to determine this is out of
-scope of this article.
 
-As an invalid workaround for correct georeferencing, many other BIM vendors
+Dealing with large coordinates
-simply offset their object coordinates from local engineering to map coordinates
+------------------------------
-without properly storing a projection system and optionally a map
-transformation. There are two common invalid workarounds that are used.
 
-The first invalid workaround is to shift the origin point of objects in the
+In scenarios 2, 3, and 4, a BIM vendor will typically choose from two possible
-model. We call this the ``OBJECT_PLACEMENT`` workaround. The second invalid
+methods to offset their coordinates into large map coordinates.
-workaround is to shift the coordinates of geometry within the objects
+
-themselves, and typically leave the object origin untouched (such as back at (0,
+The first method is to shift the origin point of objects in the model relative
-0, 0)). We call this the ``CARTESIAN_POINT`` workaround. Sometimes, BIM
+to the global coordinate system. We call this the ``OBJECT_PLACEMENT`` method.
-applications combine both of these invalid workarounds. To see which workaround
+The second method is to shift the coordinates of geometry within the objects
-was used on an object, check the "Blender Offset" property in the ``Transform``
+themselves relative to the object placement. We call this the
-object panel.
+``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. This creates a problem, because either we can display the
+still at 0, 0, 0. Since these coordinates are so far apart, this creates a
-walls accurately, or the site placement accurately, but not both. Users may not
+problem, because Blender needs to choose between displaying the walls accurately
-even realise this is an issue because many IFC viewers don't show object
+and sacrificing precision at the site placement, or vice versa, but it is
-placements because they are "invisible". However, because the BlenderBIM Add-on
+impossible to satisfy both simultaneously in the same Blender session.
-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 which offset to choose.
-In the absence of manual intervention, the BlenderBIM Add-on will make an
-intelligent guess, but it may be wrong.
 
-To manually specify an offset, simply load an IFC project with Advanced Mode
+Many IFC viewers only show geometry, and don't show object placements. This may
-enabled. Then enable the ``Import and Offset Model`` option and specify a new
+give users the false impression that their coordinates in their IFC project do
-coordinate to replace the origin's default of 0,0,0 in the ``Model Offset
+not have such a large range. However, because the BlenderBIM Add-on is a full
-Coordinates`` option.
+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
 --------------------------------
@@ -86,6 +89,7 @@ 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).
+constant for small sites (defined approximately as less than 1km square).  This
-This practical limit of georeferenced vertical construction is smaller than the
+practical limit of georeferenced vertical construction is smaller than the
-software limit, so this is the actual limiting factor.
+software limit, so this surveying convention is the actual limiting factor, not
+the software.