Output configuration

Name	Description	Type	Default value	Required
directory	Output folder where results are stored	string	No	Yes
product_level	Output requested products (dsm, point_cloud, depth_map)	list or string	“dsm”	No
resolution [1]	Output DSM grid step (only for dsm product level)	float	None [1]	No
auxiliary	Selection of additional files in products	dict	See below	No
epsg	EPSG code	int, string	None	No
geoid	Output geoid	bool or string	True	No
save_by_pair	Save output point clouds by pair	bool	False	No

---
output:
  directory: outresults # output to ./outresults
  product_level: # ask for both a dsm and the depth maps
  - dsm
  - depth_map
  geoid: true # a dsm height of 0 should be at the geoid level

{
    "output": {
        "directory": "outresults",
        "product_level": [
            "dsm",
            "depth_map"
        ],
        "geoid": true
    }
}

The product_level attribute defines which product should be produced by CARS. There are three available product type: depth_map, point_cloud and dsm.

A single product can be requested by setting the parameter as string or several products can be requested by providing a list.

This is the default behavior of CARS : a single DSM will be generated from one or several pairs of images.

The smallest configuration can simply contain those inputs.

---
input:
  sensors:
    one: img1.tif
    two: img2.tif
    three: img3.tif
  pairing:
  - - one
    - two
  - - one
    - three
  output:
    directory: out
    product_level: dsm # optional because it is the default value of product_level

{
    "input": {
        "sensors": {
            "one": "img1.tif",
            "two": "img2.tif",
            "three": "img3.tif"
        },
        "pairing": [
            [
                "one",
                "two"
            ],
            [
                "one",
                "three"
            ]
        ],
        "output": {
            "directory": "out",
            "product_level": "dsm"
        }
    }
}

Depth maps are a way to represent point clouds as three images X Y and Z, each one representing the position of a pixel on its axis. They are an official product of CARS.

The product_level key in output can contain any combination of the values dsm, depth_map, and point_cloud.

Depth maps (one for each sensor pair) will be saved if depth_map is present in product_level :

---
input:
  sensors:
    one: img1.tif
    two: img2.tif
output:
  directory: out
  product_level: depth_map

{
    "input": {
        "sensors": {
            "one": "img1.tif",
            "two": "img2.tif"
        }
    },
    "output": {
        "directory": "out",
        "product_level": "depth_map"
    }
}

Just like depth maps, the point cloud is an official product of CARS. As such, all that’s needed is to add point_cloud to product_level in order for it to be generated.

---
input:
  sensors:
    one: img1.tif
    two: img2.tif
output:
  directory: out
  product_level: point_cloud

{
    "input": {
        "sensors": {
            "one": "img1.tif",
            "two": "img2.tif"
        }
    },
    "output": {
        "directory": "out",
        "product_level": "point_cloud"
    }
}

BASIC USAGE

Additional auxiliary files can be produced by setting the auxiliary dictionary attribute.

Name	Description	Type	Default value	Required
image	Save output orthorectified image	bool, str, list	True	No
classification	Save output classification map	bool, dict, list	False	No
filling	Save output filling	bool, dict	False	No
performance_map	Save output performance map	bool, list	False	No
weights	Save output dsm weights	bool	False	No
contributing_pair	Save output contributing pair	bool	False	No
ambiguity	Save output ambiguity	bool	False	No
edges	Save output edge rasters (depth_map only)	bool	False	No

In the table below, the default value corresponds to the value used if parameter is set to True. For the classification, the output values will correspond to the input ones.

Name	Description	Type	Default value	Required
image	Define the order of the bands on the output image	list	[b0, b1, b2] (phr images), [b1, b0, b2] (co3d images)	No
classification	Edit and/or merge the values of the classification map	dict	{n:n} with n the label of the classification	No
filling	Edit and/or merge the values of the filling map	dict	{0: “no_data”, 1: “no_edition”, 2: “fill_with_exogenous_dem”, 4: “fill_with_endogenous_dem”, 5: “interpolate_from_borders”, 6: “fill_with_geoid”, 7: “other”}	No
performance_map	List defining intervals used in the performance map classification	list	[0, 0.968, 1.13375, 1.295, 1.604, 2.423, 3.428]	No

---
output:
  directory: outresults
  auxiliary:
    image: false
    weights: true
    classification: true
    filling: true
    performance_map: true

{
    "output": {
        "directory": "outresults",
        "auxiliary": {
            "image": false,
            "weights": true,
            "classification": true,
            "filling": true,
            "performance_map": true
        }
    }
}

Note that not all rasters associated to the DSM that CARS can produce are available in the output product auxiliary data. For example, confidence intervals are not part of the output product but can be found in the rasterization dump_dir if save_intermediate_data is activated in the rasterization application configuration.

Note

The auxiliary parameter edges currently acts at triangulation level. When enabled, it exports edge data in the depth map product (depth_map in product_level). It currently does not work with DSM auxiliary outputs, and won’t save additional data for the DSM.

ADVANCED USAGE

For some auxiliary data, output options can be configured inside this dictionary by overloading the boolean parameter.

For each auxiliary file, if a non-boolean parameter is given, the file is saved according to this parameter.

---
output:
  directory: outresults
  auxiliary:
    image: b1
    weights: true
    classification: 
      17: [1, 2] 
      3: 3
      15: 4
    filling: {18: [fill_with_geoid, interpolate_from_borders], 3: fill_with_endogenous_dem}
    performance_map: [0, 0.8, 0.9, 1.1, 1.2]

{
    "output": {
        "directory": "outresults",
        "auxiliary": {
            "image": "b1",
            "weights": true,
            "classification": {
                "17": [
                    1,
                    2
                ],
                "3": 3,
                "15": 4
            },
            "filling": {
                "18": [
                    "fill_with_geoid",
                    "interpolate_from_borders"
                ],
                "3": "fill_with_endogenous_dem"
            },
            "performance_map": [
                0,
                0.8,
                0.9,
                1.1,
                1.2
            ]
        }
    }
}

Image parameter:

For this specific configuration (see yaml file above), only one band (b1) is written in the output image.

Classification parameter:

For this specific configuration (see yaml file above), the output classification takes the following values:

input values	output values
[1, 2]	17
3	3
4	15

Filling parameter:

For this specific configuration (see yaml file above), the output filling takes the following values:

input values	output values
fill_with_geoid	18
interpolate_from_border	18
fill_with_endogenous_dem	3
other filling methods	default values

Performance map parameter:

For this specific configuration (see yaml file above), those values will be taken into account in the output file. You can modify the list length according to your needs.

This parameter defines the EPSG code to which the output data will be referenced. If set to None, CARS will automatically use the EPSG code of the most suitable UTM zone for the input data.

---
output:
  epsg: 4326 # 2D CRS

{
    "output": {
        "epsg": 4326
    }
}

When combined with the Geoid parameter, the EPSG ensures that the output file is assigned a CRS that also includes the corresponding vertical reference system.

---
output:
  geoid: path/to/egm08.tif # recognized geoid file
  epsg: 4326 # 3D CRS

{
    "output": {
        "geoid": "path/to/egm08.tif",
        "epsg": 4326
    }
}

Additionally, this parameter can be used to override the vertical CRS of the output data, by specifying either a 3D CRS or a CompoundCRS. For example, if the geoid provided is associated with a specific EPSG code that CARS cannot automatically detect, you can explicitly set it here.

---
output:
  geoid: path/to/black_sea_geoid.tif # not recognized by CARS
  epsg: 23037+5336 # UTM zone + the black sea VCRS, creating a CompoundCRS
  #epsg: 4978 # 3D CRS

{
    "output": {
        "geoid": "path/to/black_sea_geoid.tif",
        "epsg": "23037+5336"
    }
}

This parameter refers to the vertical reference of the output product, used as an altitude offset during triangulation. It can be set as a string to provide the path to a geoid file on disk, or as a boolean: if set to True CARS default geoid is used, if set to False no vertical offset is applied (ellipsoid reference).

If the EPSG parameter does not already define a vertical reference, a Vertical CRS (VCRS) is derived from the Geoid parameter.

If set to False, a WKT corresponding to WGS84 is used.
If set to True, the default EGM96 model (EPSG:5773) is used.
If set to a file path, the geoid file name is used to determine the appropriate VCRS. Currently, only EGM96 and EGM08 are supported.

If the provided file is not recognized, a WKT referencing the file directly is created instead.

Footnotes