19. Guide to output files¶

The parallel_stereo program (Section 16.51) generates a variety of intermediate files that are useful for debugging. These are listed below, along with brief descriptions about the contents of each file.

Some of these files are stored at the location given by the specified output prefix, while others are in subdirectories of that location corresponding to individual tiles created by parallel_stereo.

The files are listed based on the stereo stage they are created at (Section 16.51).

19.1. Files created in preprocessing¶

*-cropped*.tif

Cropped versions of the input images, before alignment, when options --left-image-crop-win and/or --right-image-crop-win are used.

*.vwip

Interest point matches per image, before matching.

If the images are left.cub and right.cub, these files end in left.vwip and right.vwip. Several interest point detection modes are available (see --ip-detect-method in Section 17).

The .vwip files can be visualized in stereo_gui (Section 16.71.10).

*.match - image-to-image interest point matches (tie-points)

The match file lists a select group of unique points out of the previous .vwip files that have been identified and matched in a pair of images. For example, if the input images are left.cub and right.cub, the match file will end in left__right.match.

The .vwip and .match files are meant to serve as cached tie-point information, and they help speed up the pre-processing phase of the Stereo Pipeline. If these files exist, then the parallel_stereo program will skip over the interest point alignment stage and instead use the cached tie-points contained in the *.match files, unless the images or cameras are newer, or if invoked with the options --left-image-crop-win or --right-image-crop-win. In the rare case that these files get corrupted, they should be deleted and parallel_stereo should be rerun.

The .match files can be visualized in stereo_gui (Section 16.71.9), and can be converted to plain text for inspection with parse_match_file.py (Section 16.52).

This program supports plain-text match files (Section 19.10).

*-L.tif - rectified left input image

Left input image of the stereo pair, after the pre-processing step, which may involve cropping, normalization of pixel values, and alignment.

*-R.tif - rectified right input image

Right input image of the stereo pair, after the pre-processing step, which may involve cropping, normalization of pixel values, and alignment.

*-lMask.tif - mask for left rectified image

This file and *-rMask.tif contain binary masks for the input images. They are used throughout the stereo process to mask out pixels where there is no input data.

*-rMask.tif - mask for right rectified image

See *-lMask.tif, above.

*-align-L.txt and R.txt - left and right alignment matrices

These 3 × 3 affine transformation matrices that are used to warp the left and right images to roughly align them. These are only generated if alignment-method is not none or epipolar (Section 17).

The older .exr format for these is still supported on reading but will be removed in the future.

*bathy_mask*.tif - data related to water-land masks, for stereo with

shallow water (Section 8.31).

*-L_sub.tif, *-R_sub.tif, *-lMask_sub.tif, *-rMask_sub.tif are

low-resolution versions of the aligned left and right input images and corresponding masks.

*-stereo.default - backup of the Stereo Pipeline settings file

This is a copy of the stereo.default file used by parallel_stereo. It is stored alongside the output products as a record of the settings that were used for this particular stereo processing task.

19.2. Files created during correlation¶

*-D_sub.tif - Low-resolution initial disparity (Section 14.3).: Computed at the correlation stage. Not recomputed when a run is resumed. The options --corr-seed-mode 2 and 3 also produce *-D_sub_spread.tif, which has the spread of this disparity. It is in the same format as D.tif (below).

*-D.tif - Full-resolution disparity map produced from the low-resolution disparity

The disparity shows the amount of horizontal and vertical shift between left and right images, in units of pixel (Section 14.2). The D.tif file contains a preliminary disparity that is used to seed the subsequent sub-pixel correlation. It is largely unfiltered, and may contain some bad matches.

Disparity map files are stored in TIF format as 3-channel, 32-bit floating point images. Channel 0 = horizontal disparity, channel 1 = vertical disparity, and channel 2 = good pixel mask.

The disparitydebug program (Section 16.23) can help inspect scaled versions of these. Or the raw bands can be extracted and visualized as in Section 16.33.1.10.

*-L-R-disp-diff.tif - the discrepancy between left-to-right and right-to-left: disparities. See option --save-left-right-disparity-difference in Section 17 for more details.
*-PC_sub.tif - triangulated point cloud image.: Made from the low-resolution disparity D_sub.tif (created after filtering this disparity; will be written unless disparity filtering is disabled, see outlier-removal-params).

19.3. Files created during blending¶

*-B.tif - disparity map blending the D.tif results from all tiles. Will be: produced unless using the asp_bm stereo algorithm without local epipolar alignment. It is in the same format as D.tif (above).

19.5. File created during filtering¶

*-F-corrected.tif - intermediate data product: Only created when alignment-method is not none. This is *-F.tif with effects of interest point alignment removed.
*-F.tif - filtered disparity map: The filtered, sub-pixel disparity map with outliers removed (and holes filled with the inpainting algorithm if FILL_HOLES is on). This is the final version of the disparity map. It is in the same format as D.tif (above).
*-GoodPixelMap.tif - map of good pixels.: An image showing which pixels were matched by the stereo correlator (gray pixels), and which were filled in by the hole filling algorithm (red pixels).

19.6. Files created at triangulation¶

*-PC.tif - point cloud image

The point cloud image is generated by the triangulation phase of Stereo Pipeline. Each pixel in the point cloud image corresponds to a pixel in the left input image (*-L.tif). The point cloud has four channels, the first three are the Cartesian coordinates of each point, and the last one has the intersection error of the two rays which created that point (Section 14.6.1). By default, the origin of the Cartesian coordinate system being used is a point in the neighborhood of the point cloud. This makes the values of the points in the cloud relatively small, and we save them in single precision (32 bits). This origin is saved in the point cloud as well using the tag POINT_OFFSET in the GeoTiff header. To output point clouds using double precision with the origin at the planet center (ECEF), call stereo_tri with the option --save-double-precision-point-cloud. This can effectively double the size of the point cloud.

If the option --compute-error-vector (Section 17.5) or --propagate-errors (Section 13) is set, the point cloud will have 6 channels. The first 3 channels store, as before, the triangulated points.

*-PC-center.txt - the point cloud local origin (add this to cloud points

to convert them to ECEF). Stored in plain text. Has the same information as the POINT_OFFSET header in PC.tif.

19.7. Diagnostics files¶

*-stereo-status.txt - processing status file

As parallel_stereo runs, it updates this file. It records the current processing step (Section 16.51.7), the number of done tiles, and the total number of tiles (both for the current step). See Section 16.51.4 for more details on tiling.

For the preprocessing and filtering stages tiling is not done. Then, the number of tiles is set to 1, and the number of done tiles is 0 if this stage is in progress, and 1 if it is done.

The status is also printed to standard output as each tile gets done (unless there is only one tile).

*-tiles.shp - shapefile having the tiles

This file saves the tiles used in processing (Section 16.51.4). Each is shown as a rectangle (the units are described below). This file is produced only by parallel_stereo, and not by stereo. The padding of each tile (for asp_mgm for example) is not included.

A file named *-tiles.qml is also created. With this one present, when the shapefile is opened in QGIS, the tile index (an integer starting with zero) will be printed inside each tile.

The stereo_gui program (Section 16.71.7) can also read and display this shapefile and the indices.

Note that the actual tile list is saved in *-dirList.txt.

When the images are mapprojected, the shapefile is saved in the projection of the L.tif image and can be overlaid on top L.tif and R.tif in QGIS and stereo_gui.

Otherwise the shapefile is in pixel units. The y coordinate is then written with the negative sign, so that the shapefile appears correctly on top of L.tif and R.tif in QGIS and stereo_gui.

19.8. Other files created at all stages¶

*-log* - log files

Each program invoked by parallel_stereo writes a log file containing the command name, build information, and various messages output by that program. Those are saved to the output prefix location, or to tile subdirectories, depending on the stage of processing.

The tiles are deleted after a successful run, which makes the log files in subdirectories go away. See the --keep-only option (Section 16.51.8) for how to keep all data, including the log files.

*-<program name>-resource-usage.txt - resource usage files

For Linux, write such a file for each parallel_stereo subprocess. It contains the elapsed time and memory usage, as output by /usr/bin/time. These are written to tile subdirectories, and are deleted after a successful run. See the --keep-only option for how to keep all files.

19.9. Inspection and properties of the output files¶

All the output images that are single-band can be visualized in stereo_gui (Section 16.71). The disparities can be first split into the individual horizontal and vertical disparity files using disparitydebug (Section 16.23), then they can be seen in this viewer as well.

If the input images are map-projected (georeferenced) and the alignment method is none, all the output images listed above, will also be georeferenced, and hence can be overlaid in stereo_gui on top of the input images (the outputs of disparitydebug will then be georeferenced as well).

The point cloud file saves the datum (and projection if available) inferred from the input images, regardless of whether these images are map-projected or not.

The point2mesh (Section 16.58) and point2dem (Section 16.56) programs can be used to convert the point cloud to formats that are easier to visualize.

19.10. Plain text match files¶

ASP programs store interest point matches between two images as a match file, in either binary format with a .match extension, or in plain text format, with a .txt extension. The latter is supported as of build 2026/02 (Section 2.1).

Plain text matches are provided for use with external logic for interest point matching. The next sections describe how to use such files and their format.

When there are multiple images, one may use pairwise match files or a control network format. See Section 16.5.10.

19.10.1. Turn on plain text matches¶

By default, ASP programs work with binary match files. The switch --matches-as-txt will enable reading and writing plain text match files instead. In that case, all existing .match files will be ignored.

This applies to bundle_adjust, parallel_stereo, jitter_solve, image_align, gcp_gen, and ipmatch.

Conversions between these formats can be done with ipmatch (Section 16.37.3). Do not use the parse_match_file.py (Section 16.52) program as that one has a different purpose.

19.10.2. Naming convention¶

Given two images input/image1.tif and input/image2.tif, and given an output prefix such as out/run, the plain-text match file name will be:

out/run-image1__image2.txt

Binary match files will have the same format but will end in .match.

The bundle_adjust program needs to be invoked with the input images and:

--match-files-prefix out/run

to read the above file. The same option is also available for parallel_stereo and jitter_solve.

Individual image names (without the path and extension) will be truncated to 60 characters to avoid excessively long file names and problems with some libraries. It is suggested to avoid using such long file names in the first place.

19.10.3. File format¶

Each line in a plain-text match file will have six numbers, in float precision, separated by spaces:

x1 y1 unc1 x2 y2 unc2

Here, x1 y1 are the coordinates of an interest point in the first image (column and row, starting from 0), unc1 is its uncertainty (in pixels), and x2 y2 unc2 are the corresponding values for the second image. In bundle adjustment each pixel is weighted by the inverse of its uncertainty. The uncertainties must be positive.

Note that this is not the same format as in parse_match_file.py (Section 16.52).

19.10.4. Inspection¶

To view plain text match files use stereo_gui (Section 16.71.9) as:

stereo_gui               \
  --matches-as-txt       \
  image1.tif image2.tif  \
  --match-file out/run-image1__image2.txt

19.11. Format of CSV files¶

Several ASP tools read and write point data as plain text CSV files, with the entries separated by commas or spaces. This includes pc_align (Section 16.53), bundle_adjust (Section 16.5), geodiff (Section 16.26), point2dem (Section 16.56), and others.

The columns are described with the --csv-format option, in quotes, as a list of entries column_index:column_type, with the index starting from 1. The columns can be in any order, and any extra columns are ignored. The recognized column types are:

x, y, z: Cartesian (ECEF) coordinates, in meters, with the origin at the planet center.
lon, lat: longitude and latitude, in degrees.
height_above_datum: height above the datum, in meters. The datum is set by the tool or via --datum (and --semi-major-axis / --semi-minor-axis).
radius_m, radius_km: distance from the planet center, in meters or kilometers.
easting, northing: projected coordinates, in meters. A PROJ or WKT string must then be set via --csv-srs.

The same format applies to all tools, and to the CSV files these tools write on output.

What follows are several concrete examples.

19.11.1. Longitude, latitude, height above datum¶

Find the difference between a DEM and a CSV file with geodiff (Section 16.26):

geodiff dem.tif file.csv                          \
  --csv-format '1:lon 2:lat 3:height_above_datum' \
  -o run

19.11.2. Easting, northing, height above datum¶

Align a DEM to a CSV file of projected measurements with pc_align (Section 16.53). A PROJ or WKT string is required to interpret the easting and northing values:

pc_align --max-displacement 100                            \
  --csv-format '1:easting 2:northing 3:height_above_datum' \
  --csv-srs 'EPSG:32610'                                   \
  dem.tif meas.csv                                         \
  -o run/run

19.11.3. LOLA, with radius in km¶

Use a LOLA point cloud as a reference terrain in bundle_adjust (Section 16.5). LOLA measurements are given as longitude, latitude, and radius from the planet center, in km:

bundle_adjust <images> <cameras>         \
  --reference-terrain lola.csv           \
  --csv-format '1:lon 2:lat 3:radius_km' \
  -o ba/run

19.12. Format of polygon files¶

The stereo_gui program can read and write polygons in the shapefile format, and also in plain text with a .txt or .csv extension (Section 16.71.7). Here the plain text format is described.

The x and y coordinates are stored as columns side-by side. Individual polygons are separated by an empty line. A color for the polygons is specified as a line of the form: color = red. The given color applies to all polygons on subsequent lines until overridden by another such statement. How to create and save such files is shown in Section 16.71.7.

When such polygons are saved, a header will be added to the file, consisting of lines starting with the pound sign, containing the WKT string for the georeference, the value of --csv-format to interpret the vertices, and the style (usually set to poly). This allows for overlaying polygons with different georeferences in stereo_gui.

The plain text polygon file supports text labels. They should be on lines that start with the text anno (annotation), followed by a space, then the x and y coordinates, separated by spaces, then the text label.