Description
The ClassifyPointsForCartography process sets values for two bands in a point cloud.
Update
A point cloud in CSAR format. Two bands, “Selection State” and “Selection Rule” are added or updated. If the bands already exist, only unclassified points are updated by the process.
Command Line Syntax
carisbatch --run ClassifyPointsForCartography --method <value> --input-band <value> [options] <update> <output>
User Interface Command
Select Points
Suppress Points
Options
The following table describes the parameters available for this process.
Option | Key | Description | Can Repeat | Notes |
|---|---|---|---|---|
Common Options | ||||
--method | A string specifying the method used to classify points. • SUPPRESSION: Classify points as Suppressed within the areas specified. • SELECT_BY_BIAS: Classify points as Selected based on a shoal or deep bias. • SELECT_BASED_ON_REFERENCE: Classify points as Selected based on an interpolated reference surface. • SELECT_LOCAL_SHOALS: Classify points as Selected if they are surrounded by deeper points. • ISOLATED_CONTOUR: Classify points as Selected within isolated closed contours. • SELECT_EXTREMA_IN_AREAS: Classify the shoalest or deepest individual points as Selected within areas. | FALSE | This must be explicitly specified. | |
--input-band | i | A string specifying the name of the input band. | FALSE | This must be explicitly specified. |
--feature-catalogue | F | A string specifying the name of the catalogue that defines the features and attributes in a vector dataset. One of { list dynamically populated from the catalogue control file }. The names of the available catalogues can be accessed through application via the Object Catalogue environment variable in Tools > Options. The available catalogues are controlled by the Catalogue Control file. An example of a catalogue name is "S-57 ENC 3.1". A catalogue must be specified when the "Features" option specifies one or more HOB files. | FALSE | |
--rule-name | The string used for the Selection Rule band for newly classified points. If no rule name is specified, there is a default value set based on the algorithm being run. | This is optional. | ||
Method = SUPPRESSION Options | ||||
--area-features | The area features that define the boundary for suppression. Only area features are considered. It is common to use the Buffer Features process to create area features from existing line and/or point features before classifying points near these features. If a suppression threshold is specified, only area features with elevation attribution are considered. | TRUE | This must be explicitly specified. | |
--elevation-lookup | A string specifying the path to a file with mappings between feature attributes and Z values. This value supersedes the Tools > Options setting for Selection Classification Lookup. This is only used if a suppression threshold is specified. | FALSE | If not specified, the value from Tools > Options for the Selection Classification Lookup setting is used. | |
--suppression-threshold | A number and unit specifying a tolerance. This is optional. If no value is specified, all points within the area features in the Area Features file(s) are classified as Suppressed. If specified, points within the area features that are deeper than (elevation + Suppression Threshold) are classified as Suppressed, for the elevation of the area feature. As such, elevation attribution must also be present in the “Features”. The suppression happens at based on a plane relative to the elevation of the area feature. If using an “up is positive” convention - which is always the convention is CARIS Batch - then positive Suppression Threshold values move the plane upwards and a subset of the points above the area features are suppressed in addition to all points below the area features. Negative Suppression Threshold values are used to only suppress a subset of the points below the area features. Inside the application, if using a “down is positive” convention, positive Suppression Threshold values move the plane downwards and only a subset of the points below the area features are suppressed, whereas negative Suppression Threshold values move the plane upwards and a subset of the points above the area features are suppressed in addition to all points below the area features. Supported units: cable, ch, cm, fm, ft, in, inm, km, m, mi, mm, nm, usfm, usft, usmi, usnm, usyd, yd | FALSE | This is optional. | |
Method = SELECT_BY_BIAS Options | ||||
--selection-method | A string specifying the algorithm used to classify points as Selected. • SHOAL_BIASED: The shoalest unclassified point is classified as Selected, iteratively. • DEEP_BIASED: The deepest unclassified point is classified as Selected, iteratively. All selection algorithms skip over a point if any Selected points are within the area of influence of that point. The Radius Coefficients determine the area of influence of each point, which can be a constant radius for all points, or it may be a depth-dependent distance. | FALSE | This must be explicitly specified. | |
--radius-coefficients | The values used to calculate the radius around each point.
<Depth unit> - Depth values are converted to this unit for this calculation. Defaults to "m", i.e. metres. The following types of radii can be used: • Fixed radius =<Coefficient 1> • Linear radius = <Coefficient 1> + <Coefficient 2> * depth • Quadratic radius = <Coefficient 1> + <Coefficient 2> * depth + <Coefficient 3> * depth^2 All selection algorithms skip over a point if any Selected points are within the area of influence of that point. The Radius Coefficients determine the area of influence of each point, which can be a constant radius for all points, or it may be a depth-dependent distance. Supported units: cable, ch, cm, fm, ft, in, inm, km, m, mi, mm, nm, usfm, usft, usmi, usnm, usyd, yd | FALSE | This must be explicitly specified. | |
--scale | s | A number specifying the scaling to apply to the Radius Coefficients (1:scale). The default scale value is 1, such that the Radius Coefficients represent the minimum distance between features on the ground; the Radius Coefficient 1 value would then be a value like 5m. A scale of 1000 would mean that the Radius Coefficients represent the minimum distance between features on a map at 1:1000 scale; the Radius Coefficient 1 value would then be a value like 10mm. | FALSE | |
--area-features | The area features that define the boundary for classification. If no Area Features inputs are specified, all points in the input are considered. It is common to use the Buffer Features process to create area features from existing line and/or point features before classifying points near these features. If Area Features inputs are specified, but there are no area features in the inputs, then no points in the input are considered. This may happen in sophisticated process models that buffer existing features, if any, and then classify points inside these buffers. | This is optional. | ||
Method = SELECT_BASED_ON_REFERENCE Options | ||||
--selection-method | A string specifying the algorithm used to classify points as Selected. • INTERPOLATION_MAX_RESIDUAL: The point farthest from a TIN is classified as Selected, iteratively. All points within a vertical tolerance of the TIN are ignored. The TIN is dynamic, based on all Selected points and the provided line features, where the line features are first densified. • INTERPOLATION_SHOALS_ONLY: The point farthest above the TIN is classified as Selected, iteratively. All points below the TIN are ignored, as are points within a vertical tolerance of the TIN. The TIN is dynamic, based on all Selected points and the provided line features, where the line features are first densified. • INTERPOLATION_DEEPS_ONLY: The point farthest below the TIN is classified as Selected, iteratively. All points above the TIN are ignored, as are points within a vertical tolerance of the TIN. The TIN is dynamic, based on all Selected points and the provided line features, where the line features are first densified. All selection algorithms skip over a point if any Selected points are within the area of influence of that point. The Radius Coefficients determine the area of influence of each point, which can be a constant radius for all points, or it may be a depth-dependent distance. | FALSE | This must be explicitly specified. | |
--reference-features | The features with elevation used to create the reference surface used to classify points. Only features with elevation attribution (e.g. contour lines, wreck point objects, et cetera) are used to create the reference surface, along with any points classified as Selected. | TRUE | This must be explicitly specified. | |
--elevation-lookup | A string specifying the path to a file with mappings between feature attributes and Z values. This value supersedes the Tools > Options setting for Selection Classification Lookup. | FALSE | If not specified, the value from Tools > Options for the Selection Classification Lookup setting is used. | |
--vertical-tolerance | A number and unit specifying the distance from the reference surface to consider as significant. This is the value that is close enough to the reference to no longer search for additional points. This is mandatory if Vertical Tolerance Percentage is not specified. If both Vertical Tolerance and Vertical Tolerance Percentage are specified, both values are calculated for each input point, and the largest of the two values is used. Supported units: cable, ch, cm, fm, ft, in, inm, km, m, mi, mm, nm, usfm, usft, usmi, usnm, usyd, yd | FALSE | This must be explicitly specified if needed. | |
--vertical-tolerance-percentage | A number specifying a percentage of depth to consider as significant. This is the value that is close enough to the reference to no longer search for additional points. This is mandatory if Vertical Tolerance is not specified. If both Vertical Tolerance and Vertical Tolerance Percentage are specified, both values are calculated for each input point, and the largest of the two values is used. The valid values are 0-100. | FALSE | This must be explicitly specified if needed. | |
--radius-coefficients | The values used to calculate the radius around each point.
The following types of radii can be used: • Fixed radius =<Coefficient 1> • Linear radius = <Coefficient 1> + <Coefficient 2> * depth • Quadratic radius = <Coefficient 1> + <Coefficient 2> * depth + <Coefficient 3> * depth^2 All selection algorithms skip over a point if any Selected points are within the area of influence of that point. The Radius Coefficients determine the area of influence of each point, which can be a constant radius for all points, or it may be a depth-dependent distance. Supported units: cable, ch, cm, fm, ft, in, inm, km, m, mi, mm, nm, usfm, usft, usmi, usnm, usyd, yd | FALSE | This must be explicitly specified. | |
--scale | s | A number specifying the scaling to apply to the Radius Coefficients (1:scale). The default scale value is 1, such that the Radius Coefficients represent the minimum distance between features on the ground; the Radius Coefficient 1 value would then be a value like 5m. A scale of 1000 would mean that the Radius Coefficients represent the minimum distance between features on a map at 1:1000 scale; the Radius Coefficient 1 value would then be a value like 10mm. | FALSE | |
--area-features | The area features that define the boundary for classification. If no Area Features inputs are specified, all points in the input are considered. It is common to use the Buffer Features process to create area features from existing line and/or point features before classifying points near these features. If Area Features inputs are specified, but there are no area features in the inputs, then no points in the input are considered. This may happen in sophisticated process models that buffer existing features, if any, and then classify points inside these buffers. | TRUE | This is optional. | |
Method = SELECT_LOCAL_SHOALS Options | ||||
--vertical-tolerance-percentage | A number specifying a percentage of depth to consider as significant. This is the value that the surrounding points have to be deeper than the given point for it to be considered as a significant shoal. The valid values are 0-100. The default is 10 percent. | FALSE | ||
--radius-coefficients | The values used to calculate the radius around each point.
The following types of radii can be used: • Fixed radius =<Coefficient 1> • Linear radius = <Coefficient 1> + <Coefficient 2> * depth • Quadratic radius = <Coefficient 1> + <Coefficient 2> * depth + <Coefficient 3> * depth^2 All selection algorithms skip over a point if any Selected points are within the area of influence of that point. The Radius Coefficients determine the area of influence of each point, which can be a constant radius for all points, or it may be a depth-dependent distance. Supported units: cable, ch, cm, fm, ft, in, inm, km, m, mi, mm, nm, usfm, usft, usmi, usnm, usyd, yd | FALSE | This must be explicitly specified. | |
--scale | s | A number specifying the scaling to apply to the Radius Coefficients (1:scale). The default scale value is 1, such that the Radius Coefficients represent the minimum distance between features on the ground; the Radius Coefficient 1 value would then be a value like 5m. A scale of 1000 would mean that the Radius Coefficients represent the minimum distance between features on a map at 1:1000 scale; the Radius Coefficient 1 value would then be a value like 10mm. | FALSE | |
--area-features | The area features that define the boundary for classification. If no Area Features inputs are specified, all points in the input are considered. It is common to use the Buffer Features process to create area features from existing line and/or point features before classifying points near these features. If Area Features inputs are specified, but there are no area features in the inputs, then no points in the input are considered. This may happen in sophisticated process models that buffer existing features, if any, and then classify points inside these buffers. | TRUE | This is optional. | |
Method = ISOLATED_CONTOUR Options | ||||
--selection-method | A string specifying the algorithm used to classify points as Selected. • SHOAL: The shoalest unclassified point in each shoal isolated closed contour is classified as Selected. • DEEP: The deepest unclassified point in each deep isolated closed contour is classified as Selected. If a previously selected point is present in the closed contour, no new point is classified as Selected. | FALSE | This must be explicitly specified. | |
--contour features | The lines with elevations considered as potential isolations when classifying the points. Only line features with elevation attribution are considered. | TRUE | This must be explicitly specified. | |
--reference-area-features | The areas with elevations used as a reference to determine the type of isolation and to interpret certain open contours as isolations. Only area features with elevation attribution are considered. If areas with elevations are present in the Reference Area Features file(s), then an open contour that ends at a boundary is treated as an isolation if no other contours are present inside this enclosed area. The algorithm requires knowing whether a given isolation is a shoal isolation or a deep isolation. This can be determined if the isotyp attribute value is populated for the contour in a HOB file or similar feature source, or if corresponding depth areas with elevation attribution are also present in the Reference Area Features file(s). | TRUE | This is optional. | |
--elevation-lookup | A string specifying the path to a file with mappings between feature attributes and Z values. This value supersedes the Tools > Options setting for Selection Classification Lookup. | FALSE | If not specified, the value from Tools > Options for the Selection Classification Lookup setting is used. | |
Method = SELECT_EXTREMA_IN_AREAS Options | ||||
--selection-method | A string specifying the algorithm used to classify points as Selected. • SHOAL: The shoalest unclassified point in each area is classified as Selected. • DEEP: The deepest unclassified point in each area is classified as Selected. This algorithm ignores any previously classified points. | FALSE | This must be explicitly specified. | |
--area-features | The area features in each of which an unclassified point is to be classified as Selected. If no Area Features inputs are specified, all points in the input are considered. It is common to use the Buffer Features process to create area features from existing line and/or point features before classifying points near these features. If Area Features inputs are specified, but there are no area features in the inputs, then no points in the input are considered. This may happen in sophisticated process models that buffer existing features, if any, and then classify points inside these buffers. If all of the points within a given area feature are already classified, no change is made within the area. | TRUE | ||
Examples
To use this command, refer to the following examples.
Suppression Example | ||
Objective | Classify points as suppressed. | |
Description | Command Line Syntax | |
The classification method is SUPPRESSION. | --method SUPPRESSION | |
The features identifying the points to be classified are in the areas.hob file in the D:\BatchSample directory. | --area-features D:\BatchSample\areas.hob | |
The Area Features file is using the S-57 ENC 3.1 catalogue. | --feature-catalogue "S-57 ENC 3.1" | |
Values will be read from the Depth band of the input coverage. | --input-band Depth | |
The coverage containing the points to be classified is called Input.csar and is located in D:\BatchSample. | D:\BatchSample\Input.csar | |
Command Line | carisbatch --run ClassifyPointsForCartography --method SUPPRESSION ‑-area-features D:\BatchSample\areas.hob --feature-catalogue "S-57 ENC 3.1" --input-band Depth D:\BatchSample\Input.csar | |
Result | All points within any areas in the Area Features file are classified as Suppressed. | |
Selection Example | ||
Objective | Classify the shoalest points in a coverage as Selected. | |
Description | Command Line Syntax | |
The classification method is SELECT_BY_BIAS. | --method SELECT_BY_BIAS | |
The SHOAL_BIASED selection method will be used. | --selection-method SHOAL_BIASED | |
A fixed radius of 20m will be used. | --radius-coefficients 20m CARIS:NONE CARIS:NONE m | |
Values will be read from the Depth band of the input coverage. | --input-band Depth | |
The coverage containing the points to be classified is called Input.csar and is located in D:\BatchSample. | D:\BatchSample\Input.csar | |
Command Line | carisbatch --run ClassifyPointsForCartography --method SELECT_BY_BIAS --selection-method SHOAL_BIASED --radius-coefficients 20m CARIS:NONE CARIS:NONE m --input-band Depth D:\BatchSample\Input.csar | |
Result | The shoalest points are classified as Selected, starting from the shoalest point in the point cloud, whenever there is no Selected point within a 20m radius of the current point. | |