1.. _mg4lidar_view_point_cloud:
2
3================================================
4Specification for MrSID/MG4 LiDAR View Documents
5================================================
6
7Version 1.0
8
9Introduction
10------------
11
12This document specifies the contents of an XML document used as a "view" into a LiDAR point cloud.  It is intended to be a rigorous definition of an XML-based format for specifying rasterization of point cloud data.  If you are looking for "something to get me started very quickly", please see the examples below.
13
14Document Structure (informative)
15--------------------------------
16
17The overall element structure of a View document is informally shown below.  Indentation and regular expression syntax are used to intuitively indicate parent-child nesting and the number of occurrences of elements.
18
19::
20
21      PointCloudView
22            InputFile +
23            Datatype ?
24            Band *
25                  Channel ?
26                  ClassificationFilter ?
27                  ReturnNumberFilter ?
28                  AggregationMethod ?
29                  InterpolationMethod ?
30            ClassificationFilter ?
31            ReturnNumberFilter ?
32            AggregationMethod ?
33            InterpolationMethod ?
34            ClipBox ?
35            CellSize ?
36            GeoReference ?
37
38Elements
39--------
40
41Each element is specified as follows:
42
43::
44
45    ElementName
46        Cardinality:  number of occurrences allowed
47        Parents:  what element(s) may contain this element
48        Contents: what may be placed inside the element
49        Attributes:  what attributes are allowed, if any
50        Notes:  additional usage information or restriction
51
52PointClouldView
53+++++++++++++++
54
55Description:  the root element for the document
56
57Cardinality:  1
58
59Parents:  none (must be root element)
60
61Contents:  child elements as specified below:
62
63- InputFile
64- Datatype
65- Band
66- ClassificationFilter
67- ReturnNumberFilter
68- AggregationMethod
69- InterpolationMethod
70- ClipBox
71- CellSize
72- GeoReference
73
74Attributes:
75
76- version - this attribute must be present and set to the value 1.0
77
78Notes:  (none)
79
80InputFile
81+++++++++
82
83Description:  specifies an input file containing point cloud data
84
85Cardinality:  1..n
86
87Parents:  PointClouldView
88
89Contents:  string (corresponding to a filename)
90
91Attributes:  (none)
92
93Notes:
94
95- Typically the file will be a MrSID/MG4 LiDAR file, but may also be a LAS file.
96-  The file name given may have a relative or absolute path.  If relative, the path is to be expanded relative to the directory containing this View document.
97
98Datatype
99++++++++
100
101Description:  specifies the datatype to which channel data should be coerced
102
103Cardinality:  0 or 1
104
105Parents:  PointClouldView
106
107Contents:  string (corresponding to a datatype name)
108
109Attributes:  (none)
110
111Notes:
112
113- If this element is not present, the native datatype of the channel is used.
114- Legal values are derived from those returned by GDALGetDataTypeByName, as follows:
115
116    - Byte
117    - UInt16
118    - Int16
119    - UInt32
120    - Int32
121    - Float32
122    - Float64
123
124- Channel data will be coerced via a c-style cast, truncating data as necessary.
125
126Band
127++++
128
129Description:  list of which band(s) to expose and in what manner to process the band data
130
131Cardinality:  0, 1 or 3
132
133Parents:  PointClouldView
134
135Contents:  child elements as follows:
136
137- 0 or 1 Channel element
138- 0 or 1 ClassificationFilter element
139- 0 or 1 ReturnNumberFilter element
140- 0 or 1 InterpolationMethod element
141- 0 or 1 AggregationMethod element
142
143Attributes:  (none)
144
145Notes:
146
147- Not specifying any bands is the same as specifying only one with all default values.
148
149Channel
150+++++++
151
152Description:  the name of the channel in the input file
153
154Cardinality:  0 or 1 per Band element
155
156Parents:  Band
157
158Contents:  we use the following canonical names of channels
159
160- X
161- Y
162- Z
163- Intensity
164- ReturnNum
165- NumReturns
166- ScanDir
167- EdgeFlightLine
168- ClassId
169- ScanAngle
170- UserData
171- SourceId
172- GPSTime
173- Red
174- Green
175- Blue
176
177Attributes:  (none)
178
179Notes:
180
181- Custom channels have non-canonical names, are supported, and may be specified.
182- If this element is omitted, the Channel for the Band shall default to Z.
183- The channel names are derived from PointData.h of the MG4 Decode SDK.
184
185ClassificationFilter
186++++++++++++++++++++
187
188Description:  A filter for points whose classification code is one of the specified values.
189
190Cardinality:  0 or 1 per Band element
191
192Parents:  Band or PointCloudView
193
194Contents:  space-separated "Classification Values" (0-31) as defined by ASPRS Standard LIDAR Point Classes in the LAS 1.3 Specification.
195
196Attributes:  (none)
197
198Notes:
199
200- If this element is omitted, the band shall have no classification filter applied.
201- If this element is a child of the PointCloudView element, it applies to all bands (unless overridden for a specific band)
202- If this element is a child of a Band element, it applies to this band only and overrides any other setting
203- Note that numbers are used to represent the filters, rather than strings.  This is because there is no canonical, simple naming convention for them, and is also in keeping with existing practice in certain existing applications.
204
205ReturnNumberFilter
206++++++++++++++++++
207
208Description:  A filter for points whose return number is one of the specified values.
209
210Cardinality:  0 or 1 per Band element
211
212Parents:  Band or PointCloudView
213
214Contents:  space-separated numbers (1, 2, ...) or the string LAST
215
216Attributes:  (none)
217
218Notes:
219
220- If this element is omitted, the band shall have no return number filter applied
221- If this element is a child of the PointCloudView element, it applies to all bands (unless overridden for a specific band)
222- If this element is a child of a Band element, it applies to this band only and overrides any other setting
223
224AggregationMethod
225+++++++++++++++++
226
227Description:  Each cell (pixel) can expose a single value.  When 2 or more points fall on a single cell, this method determines what value to expose.
228
229Cardinality:  0 or 1 per Band element
230
231Parents:  Band or PointCloudView
232
233Contents:  a string, one of Min, Max, or Mean
234
235Attributes:  (none)
236
237Notes:
238
239- If this element is omitted, the band shall have the "Mean" aggregation method applied
240- If this element is a child of the PointCloudView element, it applies to all bands (unless overridden for a specific band)
241- If this element is a child of a Band element, it applies to this band only and overrides any other setting
242
243InterpolationMethod
244+++++++++++++++++++
245
246Description:  Method and parameter to interpolate NODATA values.  Also specifies what the NODATA value is.
247
248Cardinality:  0 or 1 per Band element
249
250Parents:  Band or PointCloudView
251
252Contents:   exactly one of the following elements:
253
254- None
255
256- InverseDistanceToAPower
257
258- MovingAverage
259
260- NearestNeighbor
261
262- Minimum
263
264- Maximum
265
266- Range
267
268Attributes:  (none)
269
270Notes
271
272- Each of the interpolation methods (MovingAverage, etc.) is an element whose content is a text string corresponding to the parameter(s) for that method.  See :ref:`gdal_grid_tut` for a description of the methods and their parameter strings.
273- In the parameter descriptions, MAX is used to indicate the value defined by libc which is the largest supportable value for the output datatype.  If you choose to override this default be sure that the number you specify will fit in the datatype you specify.
274- If this element is omitted, the band shall have the "None" interpolation method applied.
275- If this element is a child of the PointCloudView element, it applies to all bands (unless overridden for a specific band)
276- If this element is a child of a Band element, it applies to this band only and overrides any other setting
277
278ClipBox
279+++++++
280
281Description:  geographic extent of region to be viewed
282
283Cardinality:  0 or 1
284
285Parents:  PointClouldView
286
287Contents:  4 or 6 doubles; the string NOFILTER may be specified in place of a double value
288
289Attributes:  (none)
290
291Notes:
292
293- The full 6 values are (in order): xmin, xmax, ymin, ymax, zmin, zmax.
294- The string NOFILTER means to use the corresponding value of the Minimum Bounding Rectangle (MBR) of the input files.  The point is not filtered by that value.
295- If only 4 double are present, the zmin and zmax are assumed to be NOFILTER.
296- If this element is not present, the clip box is assumed to be the MBR of the input files.
297
298CellSize
299++++++++
300
301Description:  Side length of a (square) pixel in ground units
302
303Cardinality:  0 or 1
304
305Parents:  PointClouldView
306
307Contents:  1 double
308
309Attributes:  (none)
310
311Notes:
312
313- This element is used to determine the size of the resulting raster.
314- If this element is omitted, the default cell size is the average (linear) point spacing (assuming a uniform distribution over the entire extent).
315
316GeoReference
317++++++++++++
318
319Description:  the coordinate reference system of the view
320
321Cardinality:  0 or 1
322
323Parents:  PointClouldView
324
325Contents:  a string (corresponding to a WKT)
326
327Attributes:  (none)
328
329Notes:
330
331- If this element is omitted, the WKT of the input files is used.  If two or more files have different WKTs, then no GeoReference is defined.
332- A typical use of this element is for when the MG4 file was created without adequate GeoReference information: cases where some combination of UOM, HorizCS and VertCS are missing are quite common.
333
334Additional Requirements
335-----------------------
336
337Any element not recognized should be treated as an error.
338
339Any attribute not recognized should be treated as an error.
340
341This specification does not mandate the lexical ordering of the child elements within a given parent.
342
343Examples
344--------
345
346Simplest possible .view file
347++++++++++++++++++++++++++++
348
349The simplest way to view an MG4 file is to wrap it in a View (.view) file like this.  Here, the relative reference to the MG4 file means that the file must exist in the same directory as the .view file.  Since we're not mapping any bands explicitly, we get the default, which is elevation only.  By default, we aggregate based on mean.  That is, if two (or more) points land on a single cell, we will expose the average of the two.  There's no filtering here so we'll get all the points regardless of classification code or return number.  Since the native datatype of elevation is "Float64", that is the datatype of the band we will expose.
350
351.. code-block:: xml
352
353    <PointCloudView>
354        <InputFile>Tetons.sid</InputFile>
355    </PointCloudView>
356
357
358Crop the data
359+++++++++++++
360
361This is similar to the example above but we are using the optional ClipBox tag to select a 300 meter North-South swatch through the cloud.  If we wanted to crop in the East-West directions, we could have specified that explicitly instead of using NOFITLER for those.  Similarly, we could also have cropped in the Z direction as well.
362
363.. code-block:: xml
364
365    <PointCloudView>
366    <InputFile>Tetons.sid</InputFile>
367    <ClipBox>505500 505800 NOFILTER NOFILTER</ClipBox>
368    </PointCloudView>
369
370
371Expose as a bare earth (Max) DEM
372++++++++++++++++++++++++++++++++
373
374Here, we expose a single band (elevation) but we want only those points that have been classified as "Ground."  The ClassificationFilter specifies a value of 2 - the ASPRS Point Class code that stipulates "Ground" points. Additionally, instead of the default "Mean" aggregation method, we specify "Max."  This means that if two (or more) points land on a single cell, we expose the larger of the two elevation values.
375
376.. code-block:: xml
377
378    <PointCloudView>
379        <InputFile>E:\ESRIDevSummit2010\Tetons.sid</InputFile>
380        <Band> <!-- Max Bare Earth-->
381            <Channel>Z</Channel>
382            <AggregationMethod>Max</AggregationMethod>
383            <ClassificationFilter>2</ClassificationFilter>
384        </Band>
385    </PointCloudView>
386
387Intensity image
388+++++++++++++++
389
390Here we expose an intensity image from the point cloud.
391
392.. code-block:: xml
393
394    <PointCloudView>
395        <InputFile>Tetons.sid</InputFile>
396        <Band>
397            <!-- All intensities -->
398            <Channel>Intensity</Channel>
399        </Band>
400    </PointCloudView>
401
402RGB image
403+++++++++
404
405Some point cloud images include RGB data.  If that's the case, you can use a .view file like this to expose that data.
406
407.. code-block:: xml
408
409    <PointCloudView>
410        <InputFile>Grass Lake Small.xyzRGB.sid</InputFile>
411        <Band>
412            <Channel>Red</Channel>
413        </Band>
414        <Band>
415            <Channel>Green</Channel>
416        </Band>
417        <Band>
418            <Channel>Blue</Channel>
419        </Band>
420    </PointCloudView>
421