1 Draft PCL JSON Specification¶
Author: | Bradley J. Chambers (RadiantBlue Technologies, Inc.) |
---|---|
Revision: | 0.2 |
Date: | 13 December 2016 |
Copyright: | Copyright (c) 2014-2016, RadiantBlue Technologies, Inc. This work is licensed under a Creative Commons Attribution 3.0 United States License. |
The PCL JSON specification is a point cloud processing pipeline interchange format based on JavaScript Object Notation (JSON), drawing inspiration from both GeoJSON and TopoJSON.
2 Introduction¶
A PCL JSON array represents a processing pipeline.
A complete PCL JSON data structure is always an array of objects (in JSON terms). In PCL JSON, an object consists of a collection of name/value pairs – also called members. For each member, the name is always a string. Member values are either a string, number, object, array or one of the literals: “true”, “false”, and “null”. An array consists of elements where each element is a value as described above.
2.1 Examples¶
A very simple PCL JSON pipeline:
[
{
"name": "VoxelGrid",
"setLeafSize":
{
"x": 1.0,
"y": 1.0,
"z": 1.0
}
}
]
A more complex pipeline, containing two filters:
[
{
"name": "PassThrough",
"setFilterFieldName": "z",
"setFilterLimits":
{
"min": 410.0,
"max": 440.0
}
},
{
"name": "StatisticalOutlierRemoval",
"setMeanK": 8,
"setStddevMulThresh": 0.2
}
]
A PCL pipeline is embedded within a PDAL pipeline as the “methods” option to filters.pclblock as shown below:
{
"pipeline": [
"input.las",
{
"type": "filters.pclblock",
"methods": [
{
"name": "VoxelGrid",
"setLeafSize":
{
"x": 1.0,
"y": 1.0,
"z": 1.0
}
}
]
},
"output.las"
]
}
2.2 Definitions¶
- JavaScript Object Notation (JSON), and the terms object, name, value, array, and number, are defined in IETF RTC 4627, at http://www.ietf.org/rfc/rfc4627.txt.
- The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this documention are to be interpreted as described in IETF RFC 2119, at http://www.ietf.org/rfc/rfc2119.txt.
3 PCL JSON Objects¶
PCL JSON always consists of a single array of PCL JSON objects. This array (referred to as the PCL JSON array below) represents a processing pipeline.
- The PCL JSON array may have any number of PCL JSON objects.
- A PCL JSON object shall have a “name” member that identifies a supported PCL filter (as documented below).
- A PCL JSON object may have any number of members (name/value pairs).
3.1 Filters¶
A filter is any of the PCL filters that has been exposed through the PCL pipeline class.
In the following descriptions, all parameters are optional unless otherwise noted.
Any JSON keys not recognized by the spec are blissfully ignored.
3.1.1 ApproximateProgressiveMorphologicalFilter (APMF)¶
This filter removes nonground points to produce a bare-earth point cloud. It is similar to the ProgressiveMorphologicalFilter, but is potentially faster (and correspondingly less accurate).
PCL details: http://docs.pointclouds.org/trunk/classpcl_1_1_approximate_progressive_morphological_filter.html
Example:
[
{
"name": "ApproximateProgressiveMorphologicalFilter",
"setMaxWindowSize": 65,
"setSlope": 0.7,
"setMaxDistance": 10,
"setInitialDistance": 0.3,
"setCellSize": 1,
"setBase": 2,
"setExponential": false,
"setNegative": false
}
]
Parameters
- setMaxWindowSize: int
- Set the maximum window size to be used for filtering ground returns. [float, default: 33]
- setSlope: float
- Set the slope value to be used in computing the height threshold. [default: 1.0]
- setMaxDistance: float
- Set the maximum height above the parameterized ground surface to be considered a ground return. [default: 2.5]
- setInitialDistance: float
- Set the initial height above the parameterized ground surface to be considered a ground return. [default: 0.15]
- setCellSize: float
- Set the cell size. [default: 1.0]
- setBase: float
- Set the base to be used in computing progressive window sizes. [default: 2.0]
- setExponential: bool
- Set flag indicating whether or not to exponentially grow window sizes. [default: true]
- setNegative: bool
- If set to false, include all points indicated by the indices (treat as “inliers”). If true, include the “outlier” points. [default: false]
3.1.2 GridMinimum¶
This filter assembles a local 2D grid over a given PointCloud, then downsamples the data.
PCL details: http://docs.pointclouds.org/trunk/classpcl_1_1_grid_minimum.html
Example:
[
{
"name": "GridMinimum",
"setResolution": 2.0
}
]
Parameters
- setResolution: float
- Set the grid resolution. [default: 1.0]
3.1.3 PassThrough¶
Description
This filter allows the user to set min/max bounds on one dimension of the data.
PCL details: http://docs.pointclouds.org/trunk/classpcl_1_1_pass_through_3_01pcl_1_1_p_c_l_point_cloud2_01_4.html
Example:
[
{
"name": "PassThrough",
"setFilterFieldName": "z",
"setFilterLimits":
{
"min": 3850100,
"max": 3850200
}
}
]
Parameters
- setFilterFieldName: string (required)
- Provide the name of the field to be used for filtering data.
Note
Only the X, Y, Z, R, G, B, and Intensity dimensions are supported.
Note
Although PDAL capitalizes the dimension names (“Z”, “Intensity”), PCL requires the names be given in lower case (“z”, “intensity”).
- setFilterLimits: object {“min”: float, “max”: float}
- Set the numerical limits for the field for filtering data. [default: {“min”: -FLT_MAX, “max”: +FLT_MAX}]
3.1.4 ProgressiveMorphologicalFilter (PMF)¶
See also
filters.pmf implements support for this operation as a PDAL filter
Description
This filter removes nonground points to produce a bare-earth point cloud.
PCL details: http://docs.pointclouds.org/trunk/classpcl_1_1_progressive_morphological_filter.html
Example:
[
{
"name": "ProgressiveMorphologicalFilter",
"setMaxWindowSize": 65,
"setSlope": 0.7,
"setMaxDistance": 10,
"setInitialDistance": 0.3,
"setCellSize": 1,
"setBase": 2,
"setExponential": false,
"setNegative": true
}
]
Parameters
- setMaxWindowSize: int
- Set the maximum window size to be used for filtering ground returns. [default: 33]
- setSlope: float
- Set the slope value to be used in computing the height threshold. [default: 1]
- setMaxDistance: float
- Set the maximum height above the parameterized ground surface to be considered a ground return. [default: 2.5]
- setInitialdistance: float
- Set the initial height above the parameterized ground surface to be considered a ground return. [default: 0.15]
- setCellSize: float
- Set the cell size. [default: 1]
- setBase: float
- Set the base to be used in computing progressive window sizes. [default: 2]
- setExponential: bool
- Set flag indicating whether or not to exponentially grow window sizes. [default: true]
- setNegative: bool
- If set to false, include all points indicated by the indices (treat as “inliers”). If true, include the “outlier” points. [default: false]
3.1.5 RadiusOutlierRemoval¶
See also
filters.outlier implements support for this operation as a PDAL filter
Description
This filter removes outliers if the number of neighbors in a certain search radius is smaller than a given K.
PCL details: http://docs.pointclouds.org/trunk/classpcl_1_1_radius_outlier_removal_3_01pcl_1_1_p_c_l_point_cloud2_01_4.html
Example:
[
{
"name": "RadiusOutlierRemoval",
"setMinNeighborsInRadius": 8,
"setRadiusSearch": 1.0
}
]
Parameters
- setMinNeighborsInRadius: int
- Set the number of neighbors that need to be present in order to be classified as an inlier. [default: 2]
- setRadiusSearch: float
- Set te radius of the sphere that will determine which points are neighbors. [default: 1.0]
3.1.6 StatisticalOutlierRemoval¶
See also
filters.outlier implements support for this operation as a PDAL filter
Description
This filter uses point neighborhood statistics to filter outlier data.
PCL details: http://docs.pointclouds.org/trunk/classpcl_1_1_statistical_outlier_removal_3_01pcl_1_1_p_c_l_point_cloud2_01_4.html
Example:
[
{
"name": "StatisticalOutlierRemoval",
"setMeanK": 8,
"setStddevMulThresh": 1.17
}
]
Parameters
- setMeanK: int
- Set the number of nearest neighbors to use for mean distance estimation. [default: 2]
- setStddevMulThresh: float
- Set the standard deviation multiplier for the distance threshold calculation. [default: 0.0]
3.1.7 VoxelGrid¶
See also
filters.voxelgrid implements support for this operation as a PDAL filter
This filter assembles a local 3D grid over a given PointCloud, then downsamples and filters the data.
PCL details: http://docs.pointclouds.org/trunk/classpcl_1_1_voxel_grid_3_01pcl_1_1_p_c_l_point_cloud2_01_4.html
Example:
[
{
"name": "VoxelGrid",
"setLeafSize":
{
"x": 1.0,
"y": 1.0,
"z": 1.0
}
}
]
Parameters
- setLeafSize: object {“x”: float, “y”: float, “z”: float}
- Set the voxel grid leaf size. [default: {“x”: 1.0, “y”: 1.0, “z”: 1.0}]