USAGE.md

Usage instructions

This document describes how to used the compiled executables of the project. Read the Build instructions first in case you have not compiled the project yet.

Algorithm testing and benchmarking

After successful compilation the railroad_benchmark executable can be used to evaluate and benchmark a single or multiple railroad infrastructure detection algorithm. Sample execution:

railroad_benchmark --input cloud.laz

Allowed options

Option	Description	Mandatory
--input <path>	input file path	YES
--seedpaths <path1> ... <pathN>	seed file paths
--seedtypes <type1> ... <typeN>	seed types for seed file paths (rail, pole, cable, ties)
--verify <path>	verifier file path
--output <path>	output directory path (default: ./)
--size <N>	maximum size of point cloud to process
--algorithm <alg1> ... <algN>	specify the algorithm pipes to execute (default: all)
--shift	shift point cloud to origo during processing to avoid precision loss (default: no)
--boundaries <minX>, <minY>, <maxX>, <maxY>	boundaries to process
--usePCDAsCache	create and use PCD file of LAZ as cache
--loglevel <level>	log level (trace, debug, info, warning, error, fatal; default: info)
--help	produce help message

Implemented algorithms

Name	Algorithm pipe	Infrastructure	Required seeds
Voronoi	CutFilter(FROM_ABOVE_VORONOI)	cable
Skeleton	CutFilter(FROM_ABOVE_SKELETON)	cable
Angle	CutFilter(FROM_ABOVE_ANGLE)	cable
Ground	GroundFilter	cable
Above	AboveFilter	cable
Density	DensityFilter	cable
AngleGround	CutFilter(FROM_ABOVE_ANGLE) GroundFilter	cable
AngleGroundAbove	CutFilter(FROM_ABOVE_ANGLE) GroundFilter AboveFilter	cable
AngleGroundAboveCylinder	CutFilter(FROM_ABOVE_ANGLE) GroundFilter AboveFilter CylinderFilter	cable
AngleGroundCylinder	CutFilter(FROM_ABOVE_ANGLE) GroundFilter CylinderFilter	cable
AngleAbove	CutFilter(FROM_ABOVE_ANGLE) AboveFilter	cable
AngleAboveCylinder	CutFilter(FROM_ABOVE_ANGLE) AboveFilter CylinderFilter	cable
VoronoiGround	CutFilter(FROM_ABOVE_VORONOI) GroundFilter	cable
VoronoiGroundAbove	CutFilter(FROM_ABOVE_VORONOI) GroundFilter AboveFilter	cable
VoronoiGroundAboveCylinder	CutFilter(FROM_ABOVE_VORONOI) GroundFilter AboveFilter CylinderFilter	cable
VoronoiGroundCylinder	CutFilter(FROM_ABOVE_VORONOI) GroundFilter CylinderFilter	cable
VoronoiAbove	CutFilter(FROM_ABOVE_VORONOI) AboveFilter	cable
VoronoiAboveCylinder	CutFilter(FROM_ABOVE_VORONOI) AboveFilter CylinderFilter	cable
GroundDensity	GroundFilter DensityFilter	cable
GroundDensityAbove	GroundFilter DensityFilter AboveFilter	cable
GroundDensityAboveCylinder	GroundFilter DensityFilter AboveFilter CylinderFilter	cable
GroundDensityCylinder	GroundFilter DensityFilter CylinderFilter	cable
HeightWidthRansac	HeightFilter WidthFilter RansacFilter	cable	CABLE (initial section)
HeightWidthHough3D	HeightFilter WidthFilter Hough3dFilter	cable	CABLE (initial section)
HeightGrowth	HeightFilter GrowthFilter	cable	CABLE (initial section)
RailTrack	RailTrackFilter	rail track
RailTrackWithSeed	WidthFilter RailTrackFilter	rail track	CABLE
PoleDetection	WidthFilter BandPassFilter OutlierFilter BandPassFilter MinDistanceClusterFilter CorrigateCentroidsFilter RansacCylinderFilter	mast	RAIL
CantileverDetection	WidthFilter HeightFilter CantileverFilter	cantilever	CABLE POLE

Sample execution:

railroad_benchmark -a PoleDetection -i cloud.laz --seedpaths railtrack.laz --seedtypes RAIL

Error detection algorithms

Name	Algorithm pipe	Infrastructure	Required seeds
StructureGaugeDetection	StructureGaugeFilter	low vegetation	RAIL
CableErrorDetection	CableDetectionFilter	cable	RAIL CABLE
GroundErrorDetection	VegetationDetectionFilter	ground	RAIL
CableStaggerCheckingFirstClass	MinHeightFilter RansacFilter StaggerFilter	cable	RAIL
CableStaggerCheckingLowerClass	MinHeightFilter RansacFilter StaggerFilter	cable	RAIL

Sample execution:

railroad_benchmark -a CableErrorDetection -i cloud.laz --seedpaths railtrack.laz cable.laz --seedtypes RAIL CABLE

Remark: the difference between the two CableStaggerChecking pipelines is the threshold for the maximum stagger (0.41 meters for first class railways vs 0.43 meters for lower class)

Combined detection

The railroad_combined executable can be used to perform combined railroad infrastructure detection (both cable and railtrack) with a given algorithm pair. Sample execution:

railroad_combined --input cloud.laz

Allowed options

Option	Description	Mandatory
--input <path>	input file path	YES
--output <path>	output directory path (default: ./)
--algorithm-cable <alg>	specify the algorithm pipe to execute for cable detection (default: AngleAbove)
--algorithm-rail <alg>	specify the algorithm pipe to execute for rail track detection (default: RailTrackWithSeed)
--size <N>	maximum size of point cloud to process
--boundaries <minX>, <minY>, <maxX>, <maxY>	boundaries to process
--usePCDAsCache	create and use PCD file of LAZ as cache
--loglevel <level>	log level (trace, debug, info, warning, error, fatal; default: info)
--help	produce help message

Remark: the result of the cable detection will be automatically used as the seed for rail track detection.

Fragmentation

The railroad_fragment executable can be used to perform fragmentation of a longer track segment to produce smaller (mostly) straight segments. Sample execution:

railroad_fragment --input cloud.laz

Allowed options

Option	Description	Mandatory
--input <path>	input file path	YES
--output <path>	output directory path (default: ./)
--algorithm <alg>	specify the filter to execute for fragmentation Possible values: ThresholdContour CannyHough, GeneralizedHough
--angle <N>	the max angle of curvation to accept before fragmentation occurs (default: 10)
--size <N>	maximum size of point cloud to process
--boundaries <minX>, <minY>, <maxX>, <maxY>	boundaries to process
--usePCDAsCache	create and use PCD file of LAZ as cache
--loglevel <level>	log level (trace, debug, info, warning, error, fatal; default: info)
--help	produce help message