Command line

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

cars -h

usage: cars [-h] [--loglevel {DEBUG,INFO,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,WARNING,ERROR,CRITICAL}
                        Logger level (default: WARNING. Should be one of (DEBUG, INFO, 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

See Configuration to learn how to write configuration file.

Loglevel parameter

The loglevel option allows to parameter the loglevel. By default, the WARNING loglevel gives few information: only criticals, errors and warnings execution messages.

Note

Use cars configfile.json --loglevel INFO to get detailed information about each CARS step.

Inputs

Images and Geometric models

Images and associated geometric models are read by the OTB. Meaning:

  • every raster GDAL knows how to read can be given as CARS input

  • geometric models can either be part of the raster image (embedded RPC) or defined within a separate file (e.g. XML DIMAP).

Note

As far as the CNES is directly concerned, CARS has mainly be tested on the following official sensors’ products. Feel free to try different products and let us know of potential errors.

  • Pléiades (PHR)

  • Sport 6/7

  • WorldView 2/3

Note

Whenever possible we strongly recommend the use of separate files to reference the geometric models. Indeed, using embedded RPC will soon be obsolete.

Optionally, one can provide CARS an additional raster that shall be projected onto the final DSM grid. This can be useful to create an ortho-image.

CARS also supports products Region Of Interest (ROI) created with otbcli_ExtractROI OTB application. See Frequently Asked Questions for details.

For more information, see Configuration.

Initial Input Digital Elevation Model

For now, CARS uses an initial input Digital Elevation Model (DEM) which is integrated in the stereo-rectification to minimize the disparity intervals to explore. Any geotiff file can be used.

For example, the SRTM data corresponding to the processed zone can be used through the otbcli_DownloadSRTMTiles OTB command.

The parameter is initial_elevation as seen in Configuration.

Masks

CARS can use a mask for each image in order to ignore some image regions (for instance water mask). This mask is taken into account during the whole 3D restitution process.

The masks can be “two-states” ones: 0 values will be considered as valid data, while any other value will be considered as invalid data and thus will be masked during the 3D restitution process.

The masks can also be multi-classes ones: they contain several values, one for each class (forest, water, cloud…). To use a multi-classes mask, a json file has to be indicated by the user in the configuration file. See the Configuration for more details.

Warning

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

Outputs

CARS produces a geotiff file named dsm.tif that contains the Digital Surface Model in the required cartographic projection and the ground sampling distance defined by the user.

If the user provides an additional input image, an ortho-image clr.tif is also produced. The latter is stackable to the DSM (See Getting Started).

These two products can be visualized with QGIS for example.

dsm.tif

clr.tif

QGIS Mix

dsm

clr

dsmclr

Simple example

A simple json file with only required configuration:

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

          }
      },
      "pairing": [["one", "two"]]
  },
  "output": {
      "out_dir": "outresults"
    }
}

Launch CARS with configuration file

cars configfile.json