Aim of module

Inference and evaluation of a trained Superpoint Transformer model.

General description

See script documentation for more details

clfSPTInfer is the inference step of the SPT workflow (clfSPTPreprocess -> clfSPTInfer). It loads a trained model bundle, classifies one or more point cloud tiles, and writes the predicted class labels back into the input file(s). If the input carries ground-truth labels, the module additionally reports evaluation metrics (OA, mIoU, mAcc) and a confusion matrix.

Module Bundle

A training run directory (Runs/Train/<timestamp>), or a standalone model bundle provides everything the module needs: the frozen config.yaml, the transforms, a checkpoint, and dataset_config.py. Its components can also be pointed to individually, for example to test a specific checkpoint other than the automatically selected best one from the same run, or when the run bundle's files have been relocated and no longer share a common -runDir. Combining a checkpoint with a config.yaml from a different run, or a manually edited one is not recommended. Unlike clfSPTTrain, the inference step requires a preprocessed tile. For each input tile, it checks for a cache in this order:

Single NAG next to the tile: used directly if its sidecar file references the same config.yaml as the currently loaded run. This is the case for tiles smaller than the subtiling grid size used during preprocessing.
Sub-tile manifest: for tiles that were split via the seam-tiling scheme during clfSPTPreprocess (mode=infer). The manifest is only used if it, and every referenced sub-NAG, matches the currently loaded config.yaml.

Predictions are computed on the superpoint hierarchy and distributed back onto the original, full-resolution points using the full-resolution indices stored in the NAG. For sub-tiled inputs, every sub-tile is classified over its full footprint (core plus a surrounding buffer of context), but only the predictions for its own core zone are kept in the final result. Points in the buffer zone of one tile are points of the core zone in the neighboring tile, so each point gets classified.

Writing Predicitons

For .odm, .las, and .laz inputs, predictions are written in-place, .copc.laz is a special case: the COPC spatial-indexing structure is not preserved when writing, so the result is a plain .laz. The point data itself is unaffected, only the query optimization is lost. For any other input format, a new file is written into the desired point format (.odm / .las) instead, carrying all original attributes plus the prediction. As a safety net, predictions are first backed up to a local file before being written to the target, if writing fails, the compute is not lost. The backup is removed again once the module completes successfully.

Parameter description

Input Options

Settings for the tiles to classify.

-tile input tile or directory to classify

Type : Path
Remark : mandatory
Description: Point cloud file (.odm, .las, .laz) or directory. Predictions are written back into the input file.

Model Options

Settings specifying the trained model used for inference.

-runDir training run directory or model bundle

Type : String
Remark : optional
Description: Must contain config.yaml (frozen transforms), Checkpoints/*.ckpt, and dataset_config.py (classes, features). Individual components can be overridden via -config, -checkpoint, -datasetConfig. Accepts: a direct run directory, '<project>/*latest' for the most recent run of a project, or '<project>/<timestamp>' as shorthand for '<project>/runs/train/<timestamp>'.

-checkpoint model checkpoint file

Type : Path
Remark : optional
Description: If not specified, the checkpoint is resolved from -runDir.

-config frozen config.yaml from training

Type : Path
Remark : optional
Description: If not specified, resolved from -runDir. Contains the transforms that must match the model.

-datasetConfig dataset_config.py with class definitions and features

Type : Path
Remark : optional
Description: If not specified, resolved from -runDir.

Output Options

Settings controlling prediction output and evaluation reports.

-attribute output attribute name for predictions

Type : String
Remark : optional, default: SPT_Class
Description: Name of the point attribute that receives the predicted class labels.

-mapBack map predictions back to original class IDs

Type : Boolean
Remark : optional, default: False
Description: If activated, predictions are remapped from internal train-IDs to the original class IDs (smallest original ID per class). If deactivated, train-IDs are written.

possible input	evaluates to
1, true, yes, Boolean(True), True	Boolean(True)
0, false, no, Boolean(False), False	Boolean(False)

-outDir output directory for metrics

Type : String
Remark : optional
Description: Directory for confusion matrix and accuracy report (only when input has ground-truth labels). If not specified, 'SPTEval_<timestamp>' is created next to the tile.

-outFormat output format for non-point-cloud inputs

Type : String
Remark : optional, default: odm
Description: Only used when the input is not .odm/.las/.laz. Native point cloud inputs are written back in-place.

odm

las

Logging Options

Settings concerning the verbosity level of logging.

-fileLogLevel Log level in the logfile

Type : LogLevel
Remark : optional, default: info

-screenLogLevel Log level on screen

Type : LogLevel
Remark : optional, default: info

-logger Logger

Type : Logger
Remark : optional
Description: Logger is usually provided by the opals framework.The user may provide their own logger object, but it has to function in the same way as the opals Logger.

Examples

Tiles must be preprocessed before inference:

clfSPTPreprocess -mode infer -runDir project_name\*latest -tile new_data.odm -tileSize 0

The -tileSize 0 flag disables sub-tiling. For large tiles (>1M points), omit this flag or set an appropriate tile size to avoid memory issues.

clfSPTInfer -runDir project_name\*latest -tile new_data.odm

Both single files and directories are accepted. Relative paths are resolved against the current working directory.