19. Guide to output files

The parallel_stereo tool 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.47).

19.1. Files created in preprocessing

*-cropped*.tif - cropped versions of the inputs, before alignment, when

--left-image-crop-win and/or --right-image-crop-win are used.

*.vwip - image feature files

If alignment-method is not none, the Stereo Pipeline will automatically search for image features to use for tie-points. Raw image features are stored in *.vwip files; one per input image. For example, if your images are left.cub and right.cub you’ll get left.vwip and right.vwip. Note: these files can also be generated by hand (and with finer grained control over detection algorithm options) using the ipfind utility.

*.match - image to image 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 your images are left.cub and right.cub you’ll get a left__right.match file.

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. In the rare case that one of these files did get corrupted or your input images have changed, you may want to delete these files and allow parallel_stereo to regenerate them automatically. This is also recommended if you have upgraded the Stereo Pipeline software.

Both .vwip and .match files can be visualized in stereo_gui (Section 16.64), and .match files can be converted to plain text for inspection with parse_match_file.py (Section 16.48).

*-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.exr - left alignment matrix

The 3 × 3 affine transformation matrices that are used to warp the left and right images to roughly align them. This file and *-align-R.exr are only generated if alignment-method is not none in the stereo.default file. Normally, a single transform is enough to warp one image to another (for example, the right image to the left). The reason we use two transforms is the following: after the right image is warped to the left, we would like to additionally transform both images so that the origin (0, 0) in the left image would correspond to the same location in the right image. This will somewhat improve the efficiency of subsequent processing.

*-align-R.exr - right alignment matrix. See *-align-L.exr, above.

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

shallow water (Section 8.27).

*-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.

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.

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

It contains integer values of disparity that are used to seed the subsequent sub-pixel correlation phase. It is largely unfiltered, and may contain some bad matches.

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

*-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.

19.4. Files created during refinement

*-RD.tif - disparity map after sub-pixel correlation

This file contains the disparity map after sub-pixel refinement. Pixel values now have sub-pixel precision, and some outliers have been rejected by the sub-pixel matching process.

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.

*-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 11.4.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, 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 14) 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 rough center of gravity.

Stored in plain text. Has the same information as the POINT_OFFSET header in PC.tif.

19.7. Other files created at all stages

*-log* - Each program writes in the output prefix location (or tile

location for parallel_stereo) a log file containing the command name, build information, and various messages output by that program.

*-<program name>-resource-usage.txt - For Linux, write such a file for each

parallel_stereo tile, containing the elapsed time and memory usage, as output by /usr/bin/time.

19.8. Format of polygon files

The stereo_gui program can read and write polygons stored in plain text with a .txt or .csv extension. 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. An example use is in Section 16.64.7.

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.64). The disparities can be first split into the individual horizontal and vertical disparity files using disparitydebug (Section 16.21), 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 overlayed 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.54) and point2dem (Section 16.52) programs can be used to convert the point cloud to formats that are easier to visualize.