API Reference

Classification

class laserfarm.Classification(input_file=None, label=None)

Bases: PipelineRemoteData

Classify points using polygons provided as shapefiles.

classification(ground_type)

Classify the pointset according to the given shape file. A new feature “ground_type” will be added to the point cloud. The value of the column identify the ground type.

Parameters:

ground_type – identifier of the groud type. 0 is not identified.

export_point_cloud(filename='', overwrite=False)

Export the classified point cloud

Parameters:

• filename – filename where to write point-cloud data

• overwrite – if file exists, overwrite

locate_shp(shp_dir)

Locate the corresponding ESRI shape file of the point cloud

Parameters:

shp_dir – directory which contains all candidate shp file for

classification

Retiling

class laserfarm.Retiler(input_file=None, label=None)

Bases: PipelineRemoteData

Split point cloud data into smaller tiles on a regular grid.

set_grid(min_x, min_y, max_x, max_y, n_tiles_side)

Setup the grid to which the input file is retiled.

Parameters:

• min_x – min x value of tiling schema

• min_y – max y value of tiling schema

• max_x – min x value of tiling schema

• max_y – max y value of tiling schema

• n_tiles_side – number of tiles along axis. Tiling MUST be square

(enforced)

split_and_redistribute(override_srs=None)

Split the input file using PDAL and organize the tiles in subfolders using the location on the input grid as naming scheme.

validate(write_record_to_file=True)

Validate the produced output by checking consistency in the number of input and output points.

Data processing

class laserfarm.DataProcessing(input=None, label=None, tile_index=(None, None))

Bases: PipelineRemoteData

Read, process and write point cloud data using laserchicken.

add_custom_feature(extractor_name, **parameters)

Add customized feature to be computed with laserchicken.

For information on the available extractors and the corresponding :param $ laserfarm data_processing extractors –help: :param $ laserfarm data_processing extractors <extractor_name> –help:

Parameters:

• extractor_name – Name of the (customizable) extractor

• parameters – Extractor-specific parameters

add_custom_features(custom_feature_list)

Add a list of customized features to be computed with laserchicken (also see add_custom_feature).

Parameters:

custom_feature_list – list of extractor names and parameters

apply_filter(filter_type, **filter_input)

Apply a filter to the environment point cloud.

For information on filter_types and the corresponding input:

$ laserfarm data_processing filter –help $ laserfarm data_processing filter <filter_type> –help

Parameters:

• filter_type – Type of filter to apply.

• filter_input – Filter-specific input.

clear_cache()

Clear KDTree’s cached by Laserchicken.

export_point_cloud(filename='', attributes='all', **export_opts)

Write environment point cloud to disk.

Parameters:

• filename – optional filename where to write point-cloud data

• attributes – List of attributes to be written in the output file

• export_opts – Optional arguments passed to the laserchicken export function

export_targets(filename='', attributes='all', multi_band_files=True, **export_opts)

Write target point cloud to disk.

Parameters:

• filename – optional filename where to write point-cloud data

• attributes – List of attributes to be written in the output file

• multi_band_files – If true, write all attributes in one file

• export_opts – Optional arguments passed to the laserchicken export function

extract_features(volume_type, volume_size, feature_names, sample_size=None)

Extract point-cloud features and assign them to the specified target point cloud.

Parameters:

• volume_type – Type of volume used to construct neighborhoods

• volume_size – Size of the volume-related parameter (in m)

• feature_names – List of the feature names to be computed

• sample_size – Sample neighborhoods with a random subset of points

property features

generate_targets(min_x, min_y, max_x, max_y, n_tiles_side, tile_mesh_size, validate=True, validate_precision=None)

Generate the target point cloud.

Parameters:

• min_x – Min x value of the tiling schema

• min_y – Min y value of the tiling schema

• max_x – Max x value of the tiling schema

• max_y – Max y value of the tiling schema

• n_tiles_side – Number of tiles along X and Y (tiling MUST be

square) :param tile_mesh_size: Spacing between target points (in m). The tiles’ width must be an integer times this spacing :param validate: If True, check if all points in the point-cloud belong to the same tile :param validate_precision: Optional precision threshold to determine whether point belong to tile

load(**load_opts)

Read point cloud from disk.

Parameters:

load_opts – Arguments passed to the laserchicken load function

normalize(cell_size)

Normalize point cloud heights.

Parameters:

cell_size – Size of the side of the cell employed for

normalization (in m) :return:

GeoTIFF export

class laserfarm.GeotiffWriter(input_dir=None, bands=None, label=None)

Bases: PipelineRemoteData

Write specified bands from point cloud data into separate geotiff files.

create_subregion_geotiffs(output_handle, EPSG=28992)

Export geotiff per sub-region, loop in band dimension

Parameters:

output_handle – Handle of output file. The output will be named

as <output_handle>_TILE_<tile ID>_BAND_<band name> :param EPSG: (Optional) EPSG code of the spatial reference system of the input data. Default 28992.

data_split(xSub, ySub)

Split the input data into sub-regions

Parameters:

• xSub – number of sub-regions in horizontal direction

• ySub – number of sub-regions in vertical direction

parse_point_cloud()

Parse input point cloud and get the following information:

• Tile list

• Length of a single band

• x and y resolution

Pipeline with remote data

class laserfarm.pipeline_remote_data.PipelineRemoteData

Bases: Pipeline

Pipeline extension to deal with remote input/output

cleanlocalfs()

remove pulled input and results (after push)

property input_folder

property input_path

property output_folder

pullremote(remote_origin)

pull directory with input file(s) from remote to local fs

Parameters:

remote_origin – path to directory on remote fs

pushremote(remote_destination)

push directory with output from local fs to remote_dir

Parameters:

remote_destination – path to remote target directory

run(pipeline=None)

Run the (augmented) pipeline

Parameters:

pipeline – (optional) Consider the input pipeline if provided

setup_local_fs(input_folder=None, output_folder=None, tmp_folder='.')

IO setup for the local file system.

Parameters:

• input_folder – path to input folder on local filesystem.

• output_folder – path to output folder on local filesystem. This folder is considered root for all output paths specified.

• tmp_folder – path of the temporary folder, used to set default input and output folders if not specified.

setup_webdav_client(webdav_options)

Pipeline

class laserfarm.pipeline.Pipeline

Bases: object

Base Pipeline class to construct workflows. Inheriting classes should define pipeline as the sequence of the methods that constitute the pipeline. After storing the input of the various tasks in the input dictionary, the pipeline can be run with the method run.

Example

>>> class FooBar(Pipeline):
...    def __init__(self):
...        self.pipeline = ['foo', 'bar']
...    def foo(self, a):
...        print(a)
...    def bar(self, b):
...        print(b)
>>> test = FooBar()
>>> test.input = {'foo': {'a': 5}, 'bar': {'b': 6}}
>>> test.run()
5
6

config(from_dict=None, from_file=None)

Set the pipeline input with a dictionary or by reading a configfile.

Parameters:

• from_dict – Input is given as a dictionary

• from_file – Path to the configfile

property input

Dictionary containing the pipeline input. Each attribute entails the input for a pipeline method that needs to be executed.

label = 'pipeline'

log_config(level=None, format=None, stream=None, filename=None)

logger = None

property pipeline

List containing the consecutive tasks that constitute the pipeline.

run(pipeline=None)

Run the full pipeline.

Parameters:

pipeline – (optional) Run the input pipeline if provided

Macro Pipeline

class laserfarm.MacroPipeline

Bases: object

Class to setup macro pipeline workflows. Each MacroPipeline object entails multiple tasks that correspond to Pipeline instances. All the tasks are run in parallel using dask.

We implement dask for embarrassingly parallel tasks, see https://examples.dask.org/applications/embarrassingly-parallel.html

Example

>>> class Foo(Pipeline):
...     def __init__(self):
...         self.pipeline = ['task_info']
...     def task_info(self):
...         print(os.getpid())
>>> macro = MacroPipeline()
>>> one, two = Foo(), Foo()
>>> macro.tasks = [one, two]
>>> macro.run() # the default thread parallelism is used
61244
61245

add_task(task)

Add pipeline instance to the collection of tasks to be executed.

Parameters:

task – Pipeline instance.

get_failed_pipelines()

print_outcome(to_file=None)

Write outcome of the tasks run. If a file path is not specified, the log outcome is printed to the standard output.

Parameters:

to_file – file path

run()

Run the macro pipeline.

set_labels(labels)

setup_cluster(mode='local', cluster=None, **kwargs)

shutdown()

property tasks

List of tasks that need to be run.