1   Draft PCL JSON Specification

Author:Bradley J. Chambers (RadiantBlue Technologies, Inc.)
Revision:0.1
Date:28 February 2014
Copyright:Copyright (c) 2014, 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 object represents a processing pipeline.

A complete PCL JSON data structure is always an object (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:

{
    "pipeline":
    {
        "name": "My cool pipeline",
        "filters":
        [
            {
                "name": "VoxelGrid",
                "setLeafSize":
                {
                    "x": 1.0,
                    "y": 1.0,
                    "z": 1.0
                }
            }
        ]
    }
}

A more complex pipeline, containing two filters:

{
    "pipeline":
    {
        "name": "CombinedExample",
        "help": "Apply passthrough filter followed by statistical outlier removal",
        "version": 1.0,
        "author": "Bradley J Chambers",
        "filters":
        [
            {
                "name": "PassThrough",
                "help": "filter z values to the range [410,440]",
                "setFilterFieldName": "z",
                "setFilterLimits":
                {
                    "min": 410.0,
                    "max": 440.0
                }
            },
            {
                "name": "StatisticalOutlierRemoval",
                "help": "apply outlier removal",
                "setMeanK": 8,
                "setStddevMulThresh": 0.2
            }
        ]
    }
}

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 object. This object (referred to as the PCL JSON object below) represents a processing pipeline.

  • The PCL JSON object may have any number of members (name/value pairs).
  • The PCL JSON object must have a “pipeline” object.

3.1   Pipeline Objects

  • A pipeline may have a member with the name “name” whose value is a string.
  • A pipeline may have a member with the name “help” whose value is a string.
  • A pipeline may have a member with the name “version” whose value is a number.
  • A pipeline must have a member with the name “filters” whose value is an array of filters.

3.1.1   Filters

A pipeline must have a “filters” member whose value is an array of zero or more 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.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:

{
    "pipeline":
    {
        "filters":
        [
            {
                "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.1.2   ConditionalRemoval

See also

filters.range implements support for this PCL operation as a PDAL filter

This filter removes normals outside of a given Z range.

PCL details: http://docs.pointclouds.org/trunk/classpcl_1_1_conditional_removal.html

Example:

{
    "pipeline":
    {
        "filters":
        [
            {
                "name": "ConditionalRemoval",
                "normalZ":
                {
                    "min": 0,
                    "max": 0.95
                }
            }
        ]
    }
}

Parameters

normalZ: object {“min”: float, “max”: float}
Set the numerical limits for filtering points based on the z component of their normal. [default: {“min”: 0.0, “max”: FLT_MAX}]

3.1.1.3   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:

{
    "pipeline":
    {
        "filters":
        [
            {
                "name": "GridMinimum",
                "setResolution": 2.0
            }
        ]
    }
}

Parameters

setResolution: float
Set the grid resolution. [default: 1.0]

3.1.1.4   NormalEstimation

Description

This filter computes the surfaces normals of the points in the input.

PCL details: http://docs.pointclouds.org/1.7.1/classpcl_1_1_normal_estimation.html

Example:

{
    "pipeline":
    {
        "filters":
        [
            {
                "name": "NormalEstimation",
                "setRadiusSearch": 2
            }
        ]
    }
}

Parameters

setKSearch: float
Set the number of k nearest neighbors to use for the feature estimation. [default: 0.0]
setRadiusSearch: float
Set the sphere radius that is to be used for determining the nearest neighbors used for the feature estimation. [default: 1.0]

3.1.1.5   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:

{
    "pipeline":
    {
        "filters":
        [
            {
                "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.1.6   ProgressiveMorphologicalFilter (PMF)

See also

filters.ground 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:

{
    "pipeline":
    {
        "filters":
        [
            {
                "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.1.7   RadiusOutlierRemoval

See also

filters.radiusoutlier 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:

{
    "pipeline":
    {
        "filters":
        [
            {
                "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.1.8   StatisticalOutlierRemoval

See also

filters.statisticaloutlier 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:

{
    "pipeline":
    {
        "filters":
        [
            {
                "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.1.9   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:

{
    "pipeline":
    {
        "filters":
        [
            {
                "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}]