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"
}

Warning

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

InputsOrchestratorPipelinesApplicationsOutputs

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	Field contains the path to the folder in which are located the srtm tiles covering the production	string	None	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
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

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	-9999	No
geomodel	geomodel associated to the image	string		Yes
geomodel_filters	filters associated to the geomodel	List of string		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.

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",
            "no_data": 0
        },
        "two": {
            "image": "img2.tif",
            "geomodel": "img2.geom",
            "no_data": 0

        },
        "three": {
            "image": "img3.tif",
            "geomodel": "img3.geom",
            "no_data": 0
        }
    },
    "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]).

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.

{
    "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"
                }
                }
            ]
        }
    }
}

Note

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

{
    "roi":
    {
        "crs" :
        {
            "type": "name",
            "properties": {
                "name": "EPSG:4326"
            }

        }
    }
}

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

Full example

Here is a full detailed example with orchestrator and applications capabilities. See correspondent sections for details.

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

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

    "orchestrator": {
        "mode":"local_dask",
        "nb_workers": 4
    },

    "pipeline": "sensors_to_dense_dsm",

    "applications":{
        "point_cloud_rasterization": {
            "method": "simple_gaussian",
            "dsm_radius": 3,
            "sigma": 0.3
        }
    },

    "output": {
      "out_dir": "outresults"
    }
  }