Usage

Command line

cars command line is the entry point for CARS to run 3D pipelines.

cars -h

usage: cars [-h] [--loglevel {DEBUG,INFO,PROGRESS,WARNING,ERROR,CRITICAL}] [--version] conf

CARS: CNES Algorithms to Reconstruct Surface

positional arguments:
  conf                  Inputs Configuration File

optional arguments:
  -h, --help            show this help message and exit
  --loglevel {DEBUG,INFO,PROGRESS,WARNING,ERROR,CRITICAL}
                        Logger level (default: PROGRESS. Should be one of (DEBUG, INFO, PROGRESS, WARNING, ERROR, CRITICAL)
  --version, -v         show program's version number and exit

CARS cli takes only one .json file as command line argument:

cars configfile.json

Note that cars-starter script can be used to instantiate this configuration file.

cars-starter  -h
usage: cars-starter [-h] -il [input.{tif,XML} or pair_dir [input.{tif,XML} or pair_dir ...]] -out out_dir [--full] [--check]

Helper to create configuration file

optional arguments:
-h, --help            show this help message and exit
-il [input.{tif,XML} or pair_dir [input.{tif,XML} or pair_dir ...]]
                        Inputs list or Pairs directory list
-out out_dir          Output directory
--full                Fill all default values
--check               Check inputs

Finally, an output used_conf.json file will be created on the output directory. This file contains all the execution used parameters and can be used as an input configuration file to re-run cars.

Configuration

This section describes main CARS configuration structure through a json configuration file.

The structure follows this organisation:

{
    "inputs": {},
    "orchestrator": {},
    "applications": {},
    "output": {},
    "pipeline": "pipeline_to_use",
    "geometry_plugin": "geometry_plugin_to_use"
}

Warning

Be careful with commas to separate each section. None needed for the last json element.

InputsOrchestratorPipelinesGeometry pluginApplicationsOutputs

Inputs depends on the pipeline used by CARS. CARS can be entered with Sensor Images or Point Clouds:

• Sensor Images: used in “sensors_to_dense_dsm”, “sensors_to_sparse_dsm”, “sensors_to_dense_point_clouds” pipelines.

• Point Clouds: used in “dense_point_clouds_to_dense_dsm” pipeline.

Sensors Images inputsPoint Clouds inputs

Name	Description	Type	Default value	Required
sensor	Stereo sensor images	See next section	No	Yes
pairing	Association of image to create pairs	list of sensor	No	Yes
epsg	EPSG code	int, should be > 0	None	No
initial_elevation	Path to SRTM tiles (see Plugins section for details) If not provided, internal dem is generated with sparse matches	string	None	No
use_endogenous_elevation	Use endogenous eleveation intead of provided initial_elevation when endogenous elevation is available If no initial_elevation, endogenous elevation is always used	bool	False	No
default_alt	Default height above ellipsoid when there is no DEM available no coverage for some points or pixels with no_data in the DEM tiles	int	0	No
roi	ROI: Vector file path or GeoJson	string, dict	None	No
debug_with_roi	Use ROI with the tiling of the entire image	Boolean	False	No
check_inputs	Check inputs consistency (to be deprecated and changed)	Boolean	False	No
geoid	Geoid path	string	Cars internal geoid	No
use_epipolar_a_priori	Active epipolar a priori	bool	False	Yes
epipolar_a_priori	Provide epipolar a priori information (see section below)	dict		No
terrain_a_priori	Provide terrain a priori information (see section below)	dict		No

Sensor

For each sensor images, give a particular name (what you want):

{
    "my_name_for_this_image":
    {
        "image" : "path_to_image.tif",
        "color" : "path_to_color.tif",
        "mask" : "path_to_mask.tif",
        "classification" : "path_to_classification.tif",
        "nodata": 0
    }
}

Name	Description	Type	Default value	Required
image	Path to the image	string		Yes
color	Image stackable to image used to create an ortho-image corresponding to the produced dsm	string		No
no_data	No data value of the image	int	0	No
geomodel	Path of geomodel and plugin-specific attributes (see Plugins section for details)	string, dict		No
mask	Binary mask stackable to image: 0 values are considered valid data	string	None	No
classification	Multiband classification image (label keys inside metadata): 1 values = valid data	string	None	No

Note

• color: This image can be composed of XS bands in which case a PAN+XS fusion has been be performed. Please, see the section Make a simple pan sharpening to make a simple pan sharpening with OTB if necessary.

• If the classification configuration file is indicated, all non-zeros values of the classification image will be considered as invalid data.

• Please, see the section Convert image to binary image to make binary mask image or binary classification with 1 bit per band.

• The classification of second input is not necessary. In this case, the applications use only the available classification.

• Please, see the section Add band name / description in tiff files metadata to add band name / description in order to be used in Applications

• geomodel: If no geomodel is provide, CARS will try to use the rpc loaded with rasterio opening image.

Pairing

The pairing attribute defines the pairs to use, using sensors keys used to define sensor images.

{
"inputs": {
    "sensors" : {
        "one": {
            "image": "img1.tif",
            "geomodel": "img1.geom"
        },
        "two": {
            "image": "img2.tif",
            "geomodel": "img2.geom"

        },
        "three": {
            "image": "img3.tif",
            "geomodel": "img3.geom"
        }
    },
    "pairing": [["one", "two"],["one", "three"]]
    }
}

Epipolar a priori

The epipolar is usefull to accelerate the preliminary steps of the grid correction and the disparity range evaluation, particularly for the sensor_to_full_resolution_dsm pipeline. The epipolar_a_priori data dict is produced during low or full resolution dsm pipeline. However, the epipolar_a_priori should be not activated for the sensor_to_low_resolution_dsm. So, the sensor_to_low_resolution_dsm pipeline produces a refined_conf_full_res.json in the outdir that contains the epipolar_a_priori information for each sensor image pairs. The epipolar_a_priori is also saved in the used_conf.json with the sensor_to_full_resolution_dsm pipeline.

For each sensor images, the epipolar a priori are filled as following:

Name	Description	Type	Default value	Required
grid_correction	The grid correction coefficients	list		if use_epipolar_a_priori is True
disparity_range	The disparity range [disp_min, disp_max]	list		if use_epipolar_a_priori is True

Note

The grid correction coefficients are based on bilinear model with 6 parameters [x1,x2,x3,y1,y2,y3]. The None value produces no grid correction (equivalent to parameters [0,0,0,0,0,0]).

Terrain a priori

The terrain a priori is used at the same time that epipolar a priori. If use_epipolar_a_priori is activated, epipolar_a_priori and terrain_a_priori must be provided. The terrain_a_priori data dict is produced during low or full resolution dsm pipeline.

The terrain a priori is initially populated with DEM information.

Name	Description	Type	Default value	Required
dem_median	DEM generated with median function	str		if use_epipolar_a_priori is True
dem_min	DEM generated with min function	str		if use_epipolar_a_priori is True
dem_max	DEM generated with max function	str		if use_epipolar_a_priori is True

Region Of Interest (ROI)

A terrain ROI can be provided by user. It can be either a vector file (Shapefile for instance) path, or a GeoJson dictionnary. These structures must contain a single Polygon or MultiPolygon. Multi-features are not supported.

Example of the “roi” parameter with a GeoJson dictionnary containing a Polygon as feature :

{
    "inputs":
    {
        "roi" : {
            "type": "FeatureCollection",
            "features": [
                {
                "type": "Feature",
                "properties": {},
                "geometry": {
                    "coordinates": [
                    [
                        [5.194, 44.2064],
                        [5.194, 44.2059],
                        [5.195, 44.2059],
                        [5.195, 44.2064],
                        [5.194, 44.2064]
                    ]
                    ],
                    "type": "Polygon"
                }
                }
            ]
        }
    }
}

If the debug_with_roi parameter is enabled, the tiling of the entire image is kept but only the tiles intersecting the ROI are computed.

MultiPolygon feature is only useful if the parameter debug_with_roi is activated, otherwise the total footprint of the MultiPolygon will be used as ROI.

By default epsg 4326 is used. If the user has defined a polygon in a different reference system, the “crs” field must be specified.

Example of the debug_with_roi mode utilizing an “roi” parameter of type MultiPolygon as a feature and a specific EPSG.

{
    "inputs":
    {
        "roi" : {
            "type": "FeatureCollection",
            "features": [
                {
                "type": "Feature",
                "properties": {},
                "geometry": {
                    "coordinates": [
                    [
                        [
                            [319700, 3317700],
                            [319800, 3317700],
                            [319800, 3317800],
                            [319800, 3317800],
                            [319700, 3317700]
                        ]
                    ],
                    [
                        [
                            [319900, 3317900],
                            [320000, 3317900],
                            [320000, 3318000],
                            [319900, 3318000],
                            [319900, 3317900]
                        ]
                    ]
                    ],
                    "type": "MultiPolygon"
                }
                }
            ],
            "crs" :
            {
                "type": "name",
                "properties": {
                    "name": "EPSG:32636"
                }
            }
        },
         "debug_with_roi": true,
    }
}

Example of the “roi” parameter with a Shapefile

{
    "inputs":
    {
        "roi" : "roi_vector_file.shp"
    }
}

Plugins

This section describes optional plugins possibilities of CARS.

Note

Work in progress !

OTB Geometry pluginShareloc Geometry plugin

By default, the geometry functions in CARS are run through otb.

To use OTB geometry library, CARS input configuration should be defined as :

{
  "inputs": {
    "sensors": {
      "one": {
        "image": "img1.tif",
        "geomodel": {
          "path": "img1.geom"
        },
      },
      "two": {
        "image": "img2.tif",
        "geomodel": {
          "path": "img2.geom"
        },
      }
    },
    "pairing": [["one", "two"]],
    "initial_elevation": "path/to/srtm_file"
  },
  "geometry_plugin": "OTBGeometry",
  "output": {
    "out_dir": "outresults"
  }
}

The standards parts are described in CARS Configuration.

The particularities in the configuration file are:

• geomodel.path: Field contains the paths to the geometric model files related to img1 and img2 respectively.

• initial_elevation: Field contains the path to the folder in which are located the SRTM tiles covering the production.

• geometry_plugin: Parameter configured to “OTBGeometry” to use OTB library.

Parameter can also be defined as a string path instead of a dictionary in the configuration. In this case, geomodel parameter will be changed to a dictionary before launching the pipeline. The dictionary will be :

{
  "path": "img1.geom"
}

Note

This library is foreseen to replace otb default in CARS for maintenance and installation ease. Be aware that geometric models must therefore be opened by Shareloc directly in this case, and supported sensors may evolve.

Overview

To summarize, CARS pipeline is organized in sequential steps from input pairs (and metadata) to output data. Each step is performed tile-wise and distributed among workers.

The pipeline will perform the following steps [Michel J. et al, 2020] [Youssefi D. et al, 2020]:

• For each stereo pair:

  1. Create stereo-rectification grids for left and right views.

  2. Resample the both images into epipolar geometry.

  3. Compute sift matches between left and right views in epipolar geometry.

  4. Predict an optimal disparity range from the filtered point cloud resulting from the sift matches triangulation.

  5. Create a bilinear correction model of the right image’s stereo-rectification grid in order to minimize the epipolar error. Apply the estimated correction to the right grid.

  6. Resample again the stereo pair in epipolar geometry (using corrected grid for the right image) by using input DTM (such as SRTM) in order to reduce the disparity intervals to explore.

  7. Compute disparity for each image pair in epipolar geometry.

  8. Fill holes in disparity maps for each image pair in epipolar geometry.

  9. Triangule the matches and get for each pixel of the reference image a latitude, longitude and altitude coordinate.

• Then

  10. Merge points clouds coming from each stereo pairs.

  11. Filter the resulting 3D points cloud via two consecutive filters: the first removes the small groups of 3D points, the second filters the points which have the most scattered neighbors.

  12. Rasterize: Project these altitudes on a regular grid as well as the associated color.