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