19. Guide to output files¶
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
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
- *.vwip - image feature files
none, the Stereo Pipeline will automatically search for image features to use for tie-points. Raw image features are stored in
*.vwipfiles; one per input image. For example, if your images are
right.vwip. Note: these files can also be generated by hand (and with finer grained control over detection algorithm options) using the
- *.match - image to image tie-points
The match file lists a select group of unique points out of the previous
.vwipfiles that have been identified and matched in a pair of images. For example, if your images are
right.cubyou’ll get a
.matchfiles 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_stereoprogram will skip over the interest point alignment stage and instead use the cached tie-points contained in the
*.matchfiles. 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_stereoto regenerate them automatically. This is also recommended if you have upgraded the Stereo Pipeline software.
- *-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
stereo.defaultfile. 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.defaultfile 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
3also 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-differencein 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
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_bmstereo 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
none. This is
*-F.tifwith 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_HOLESis 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_OFFSETin the GeoTiff header. To output point clouds using double precision with the origin at the planet center, call
stereo_triwith the option
--save-double-precision-point-cloud. This can effectively double the size of the point cloud.
- *-PC-center.txt - the point cloud rough center of gravity.
Stored in plain text. Has the same information as the
19.7. Other files created at all stages¶
- *-log* - Each program writes in the output prefix location (or tile
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_stereotile, containing the elapsed time and memory usage, as output by
19.8. Format of polygon files¶
stereo_gui program can read and write polygons stored in plain
text with a
.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
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
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.