Configuration

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

The structure follows this organisation:

{
    "inputs": {},
    "orchestrator": {},
    "applications": {},
    "output": {}
}

Warning

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

InputsOrchestratorApplicationsOutputsPipelines

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	DSM roi file or bounding box	string, list or tuple	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",
        "mask_classes" : {},
        "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	external mask of the image	string	None	No
mask_classes	mask’s classes usage (see next section for more details)	dict		No

Note

• color: This image can be composed of XS bands in which case a PAN+XS fusion will be performed.

• If the mask is a multi-classes one and no mask_classes configuration file is indicated, all non-zeros values of the mask will be considered as invalid data.

• The value 255 is reserved for CARS internal use, thus no class can be represented by this value in the masks.

CARS mask multi-classes structure

Multi-classes masks have a unified CARS format enabling the use of several mask information into the API. The classes can be used in different ways depending on the tag used in the dict defined below.

Dict is given in the mask_classes fields of sensor (see previous section). This dict indicate the masks’s classes usage and is structured as follows :

{
    "ignored_by_dense_matching": [1, 2],
    "set_to_ref_alt": [1, 3, 4],
    "ignored_by_sparse_matching": [2]
}

• The classes listed in ignored_by_sparse_matching will be masked at the sparse matching step.

• The classes listed in ignored_by_dense_matching will be masked at the dense matching step.

• The classes listed in set_to_ref_alt will be set to the reference altitude (srtm or scalar). To do so, these pixels’s disparity will be set to 0.

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]).

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

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

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