Debian Codegraph @

src/bonsai/docs/guides/authoring/georeferencing.rst

raw
1 Georeferencing
2 ==============
3
4 There are two types of construction: vertical construction (such as buildings
5 and sites) which deal with small distances typically under 1km, and horizontal
6 construction (such as transport, transmission, and subterranean networks) where
7 distances frequently exceed 1km. Blender and Bonsai focuses on vertical
8 construction, and will typically just work out of the box.
9
10 Coordinate reference systems
11 ----------------------------
12
13 The minimum requirement for a georeferenced model is to specify the coordinate
14 reference system used. This is known as the **Projected CRS**, and is a feature
15 available in IFC4 onwards.
16
17 .. warning::
18
19 IFC2X3 models cannot be georeferenced. There is a proposed convention to
20 provide fallback support but this is not supported yet in any known vendor.
21 Please consider upgrading to IFC4.
22
23 Most architects and engineers will know the name of the **Projected CRS**
24 typically chosen by the surveyor. For example in Sydney, Australia, you might
25 use GDA2020 / MGA Zone 56. In IFC a standardised code from the EPSG public
26 registry is used to refer to the **Projected CRS**. For example, GDA 2020 / MGA
27 Zone 56 will be named EPSG:7856.
28
29 You can check whether or not your model is georeferenced in the **IFC
30 Georeferencing** panel in the **Scene Properties** tab. You should see a section
31 for the **Projected CRS** with an EPSG code.
32
33 .. image:: images/projectedcrs.png
34
35 If you do not see this, your project is not georeferenced.
36
37 .. Note::
38
39 Even if a model has large "real world coordinates", this does not mean the
40 project is georeferenced. Without a **Projected CRS**, these coordinates are
41 meaningless.
42
43 Map conversions
44 ---------------
45
46 The coordinates for the nominated **Projected CRS** are known as **Map
47 Coordinates**. These **Map Coordinates** are typically large numbers and read as
48 Eastings and Northings.
49
50 In vertical construction, some disciplines (such as a civil engineer or
51 surveyor) will directly use **Map Coordinates** in their designs. Most others,
52 such as the architect, structural, and service engineers will instead use
53 **Local engineering coordinates**. A **Map Conversion** stores the parameters
54 for transforming **Local engineering coordinates** to **Map Coordinates**.
55
56 For example, a civil engineer will work directly in **Map Coordinates**. This
57 means that the model's coordinates correlate directly to Eastings and
58 Northings. Similarly, the model's +Y axis will point to **Grid North**. As
59 there is no **Map Conversion** involved, you will see a 0 in the Eastings,
60 Northings, and Orthogonal Height in the **IFC Georeferencing** panel.
61
62 .. image:: images/mapcoordinates.png
63
64 When **Local engineering coordinates** are used, typically the architect will
65 nominate a local origin and model geometry will be drawn orthogonally (i.e.
66 along the X and Y axis). This local origin often correlates with a site boundary,
67 surveyed point, or grid intersection. This means that the model's coordinates
68 are typically smaller numbers and correlate to surface distance measurements,
69 not Eastings and Northings, and the model's +Y axis will point to **Project
70 North**. The surveyor will then provide the necessary **Map Conversion**
71 parameters to convert from **Local engineering coordinates** to Eastings,
72 Northings, Orthogonal Height, and **Grid North**.
73
74 .. image:: images/mapconversion.png
75
76 .. warning::
77
78 Coordinate systems are a technical topic. A common error is that disciplines
79 may choose to use **Map Coordinates** without realising that map distances
80 do not correlate with surface distances measured on the ground. Unless you
81 are trained to work in **Map Coordinates**, it is safer to work with local
82 engineering coordinates and consult your surveyor for professional guidance.
83
84 **Map Conversions** contain six parameters.
85
86 **Eastings**, **Northings** and **Orthogonal Height** parameters define the
87 translation from the model's XYZ coordinates to map **Eastings**, **Northings**,
88 and **Heights**. Your model's local engineering origin at 0, 0, 0, will always
89 convert exactly to the **Easting**, **Northing**, and **Orthogonal Height**
90 displayed in this panel.
91
92 The **X Axis Abcissa** and **X Axis Ordinate** define the rotation vector from
93 **Project North** to **Grid North**. These two numbers combine into a coordinate
94 vector pointing along the X axis (i.e. **Project East**). The default is an
95 abscissa of 1 and ordinate of 0. This default (1, 0) vector implies **Project
96 East** and **Grid East** coalign, which means there is no rotation between
97 **Project North** and **Grid North**.
98
99 .. image:: images/xaxisabscissaordinate.png
100
101 .. tip::
102
103 To save you the mental struggle of converting to degrees, a calculated
104 rotation is always just below these values. Phew!
105
106 The distance measured on site, or the "surface distance" is actually not the
107 same as the distance measured between Eastings and Northings. This difference is
108 provided by the **Scale** parameter. The **Scale** defines the average combined
109 scale factor across the small 1km site that converts from the model's surface
110 distances to map grid distances. Note that the **Scale** is actually not a
111 constant. However, for the small sites dealt with in vertical construction, it
112 may be approximated to be a constant by your surveyor and will typically be a
113 value close to, but not exactly 1.
114
115 .. note::
116
117 Always check that the surveyor provides a scale factor such that surface
118 distance multiplied by **Scale** equals map grid distances (as opposed to
119 the other way around).
120
121 Working with Map Coordinates
122 ----------------------------
123
124 Bonsai is designed to work with small coordinates (under 1km), whereas map
125 coordinates are typically large. When you load an IFC which uses map
126 coordinates directly, or when you are working with IFC2X3 and you cannot use a
127 map conversion, Bonsai will autodetect a point on your model to use as a false
128 origin.
129
130 The XYZ offset used for the false origin will be shown in the **IFC
131 Georeferencing** panel under the **Blender Offset** header. It
132 is very similar to a **Map Conversion**, but it will not have a scale and only
133 temporarily affects your Blender session.
134
135 .. image:: images/blenderoffset.png
136
137 .. note::
138
139 A Blender offset is simply a shift in coordinates to reduce large model
140 coordinates to smaller coordinates. It should not be used as an indicator of
141 whether georeferencing is done correctly. Always check the **Projected
142 CRS**, **Map Conversion** and confirm the parameters with your surveyor.
143
144 This distance limit of 1km and autodetected false origin may not be appropriate
145 for your project. For example, your project may exceed the 1km limit, or you may
146 want to federate multiple files together and manually specify a consistent and
147 fixed false origin. You can customise these options by choosing
148 :ref:`Enable Advanced Mode <Project Info Advanced Loading Mode>` when loading a project.
149 Then, set the **Distance Limit** (in meters) and the **False Origin** coordinate
150 before pressing **Load Project Elements**.
151
152 .. image:: images/manualorigin.png
153
154 When a false origin is used, there are two possible methods to offset objects by
155 the false origin.
156
157 The first method is to offset the origin point of objects. We call this the
158 **Object Placement** method. The second method is to offset the local
159 coordinates of geometry within the objects themselves. We call this the
160 **Cartesian Point** method. Sometimes, BIM applications combine both of these
161 methods in a single IFC project. To see which workaround was used on an object,
162 check the "Blender Offset" property in the **Transform** panel in the **Object
163 Properties**. This is an advanced property used by powerusers to debug
164 coordinate issues and may be safely ignored by most users.
165
166 .. image:: images/offsetmode.png
167
168 Incorrect coordinate use
169 ------------------------
170
171 Sometimes, a model may mix **Map Coordinates** and **Local engineering
172 coordinates**. For example, a surveyed pipe may have its placement use **Map
173 Coordinates** with large Eastings and Northings. However, the placement of the
174 site object may be still set at 0, 0, 0. Since this range of coordinates exceed
175 the default 1km distance limit, this creates a problem. Blender needs to choose
176 between displaying the pipe accurately and sacrificing precision at the site
177 placement, or vice versa, but it is impossible to satisfy both simultaneously in
178 the same Blender session.
179
180 .. warning::
181
182 Many IFC viewers only show geometry, and don't show object placements. This may
183 give users the false impression that their coordinates in their IFC project
184 do not have such a large range. However, as a native IFC authoring platform,
185 Bonsai will not accept this inconsistency.
186
187 At this point, it is the users responsibility to reconcile this inconsistency in
188 their coordinates. Either the user needs to fix their file to consistently
189 offset all coordinates, or the user needs to manually tell Bonsai the
190 coordinates of the desired false origin and accept the precision loss.
191
192 Converting local and map coordinates
193 ------------------------------------
194
195 You can convert **Local engineering coordinates** to **Map coordinates** and
196 vice versa in the **Viewport** panel. First, enable ``View > Sidebar`` then type
197 in your coordinate in the **Input** field. Press either the **Local to Global**
198 or **Global to Local** button to convert the coordinate. You will see the result
199 of the calculation in the **Output** field.
200
201 .. image:: images/coordinateconversion.png
202
203 True north
204 ----------
205
206 When **Local engineering coordinates** are used, the model's +Y axis points to
207 **Project North** for the convenience of drafting. When **Map Coordinates** are
208 used, the model's +Y axis points to **Grid North** for the necessity of
209 surveying.
210
211 **Project North** and **Grid North** is different to **True North**. The angle
212 to **True North** is not a fixed angle. It will actually vary depending on the
213 Eastings and Northings you choose to calculate it from.
214
215 However, this variable **True North** is a great source of confusion to
216 architects, who typically just want to do a shadow study, solar study, or
217 similar and go out for an early lunch. IFC can store a fixed **True North**
218 value as a reference to be used for these types of usecases. If one is stored in
219 your project, you may see it under the **True North** section of the **IFC
220 Georeferencing** panel. Your surveyor will be able to provide the **True North**
221 vector, but it should be only used as a reference, never used as a way to
222 coordinate model rotations, and always with the understanding that it is not a
223 fixed value.
224
225 .. image:: images/truenorth.png
226
227 .. warning::
228
229 Fun fact: **Magnetic North** is useless for the purposes of construction.
230
231 Coordinate precision limits
232 ---------------------------
233
234 Bonsai focuses on vertical construction. Vertical construction typically uses
235 **Local engineering coordinates** on a small site. The buildingSMART
236 georeferencing technical experts panel have determined that a small site under
237 1km square can be assumed to have a constant **Map Conversion**.
238
239 Therefore, if your model is less than 1km square, you are within the coordinate
240 precision limits. This is where the 1km default distance limit is derived from.
241
242 If you want to exceed the 1km square surveying limitation, you will need to be
243 aware of software limitations that can result in precision loss when large
244 coordinate ranges are used.
245
246 Blender, and subsequently Bonsai, is not designed for **Map Coordinates**.
247 Blender internally uses single precision floating point calculations. A full
248 description of the precision implications are described in the `Blender working
249 limits documentation
250 <https://docs.blender.org/manual/en/latest/advanced/limits.html>`__.
251
252 This means that lengths greater than 5,000 meters start to accumulate software
253 precision errors that affect the nearest millimeter. Therefore, from a software
254 perspective, it is unwise to embark on a project with coordinates ranging
255 greater than +/- 5km.