asp_plot.stereo

asp_plot.stereo#

Attributes#

`INTEREST_POINT_COLOR`
`MATCH_POINT_COLOR`
`MAX_POINTS_DRAWN`
`logger`

Classes#

`PairStereoFiles`	The per-pair stereo products of one multi-view pair.
`StereoFiles`	Discover the ASP stereo output files for a processing directory.
`StereoPlotter`	Visualize and analyze stereo processing results from ASP.

Functions#

read_match_file(match_point_fn)

Read an ASP match file into a DataFrame of match points.

Module Contents#

class asp_plot.stereo.PairStereoFiles#

The per-pair stereo products of one multi-view pair.

One entry per <prefix>-pairN/ subdirectory of an ASP multi-view stereo run (see asp_plot.utils.find_pair_directories()). Field names match the corresponding StereoFiles attributes so the plotting helpers can consume either.

align_left_fn: str | None#

align_right_fn: str | None#

directory: str#

disparity_fn: str | None#

disparity_sub_fn: str | None#

label: str#

left_image_fn: str | None#

left_image_sub_fn: str | None#

left_mask_fn: str | None#

left_vwip_fn: str | None#

match_point_fn: str | None#

number: int#

right_image_sub_fn: str | None#

right_vwip_fn: str | None#

class asp_plot.stereo.StereoFiles(directory, stereo_directory, dem_gsd=None, dem_fn=None, reference_dem=None)#

Discover the ASP stereo output files for a processing directory.

This isolates file discovery (globbing for DEMs, disparity maps, match files, reference DEM, etc.) from the plotting in StereoPlotter, mirroring the ReadBundleAdjustFiles / PlotBundleAdjustFiles split. The resolved paths and flags are exposed as plain attributes, which StereoPlotter consumes.

directory#

Root directory for ASP processing.

Type:: str

stereo_directory#

Directory containing stereo processing outputs.

Type:: str

full_directory#

Full path to the stereo directory.

Type:: str

attribution#

Rights-holder of the source imagery (“Vantor”, “Airbus DS”, …); gates the copyright overlay on scene panels.

Type:: str or None

reference_dem#

Path to the reference DEM (supplied or recovered from the stereo log).

Type:: str or None

left_image_fn, left_image_sub_fn, right_image_sub_fn

Left/right (sub-sampled) image paths.

Type:: str or None

left_mask_fn#

Full-resolution left mask (*-lMask.tif). ASP writes it on the same grid as *-L.tif, so it stands in for the left image’s size and GSD when the (much larger) left image has been deleted; see full_res_left_fn().

Type:: str or None

orthos#

Whether the left image is map-projected.

Type:: bool

align_left_fn, align_right_fn

Alignment transform text files.

Type:: str or None

match_point_fn#

Match-point file, binary .match or plain-text .txt (the non--disp- one when several exist); None when the directory has none at the top level (e.g. a multi-view run, whose match files live in the run-pair*/ subdirectories).

Type:: str or None

left_vwip_fn, right_vwip_fn

Per-image raw interest point files (.vwip) for the left and right images; either may be None (they are intermediates that ASP runs sometimes clean up, and some runs keep only the left file).

Type:: str or None

disparity_sub_fn, disparity_fn

Sub-sampled and full disparity map paths.

Type:: str or None

pairs#

Per-pair products of a multi-view run, resolved from the <prefix>-pairN/ subdirectories; empty for a standard stereo run.

Type:: list of PairStereoFiles

dem_gsd#

Ground sample distance of the DEM in meters.

Type:: float or None

dem_fn#

Path to the stereo DEM.

Type:: str

intersection_error_fn#

Triangulation intersection-error raster.

Type:: str or None

static full_res_left_fn(files)#

A raster on the full-resolution left image grid, or None.

The match-point and disparity figures need the full-resolution size (or GSD) only to rescale onto the sub-sampled images. *-L.tif is preferred; *-lMask.tif has the same size and georeferencing and survives when the left image, one of the largest files ASP writes, is deleted to save disk space. Accepts a StereoFiles or PairStereoFiles.

align_left_fn#

align_right_fn#

attribution = None#

dem_gsd = None#

directory#

disparity_fn#

disparity_sub_fn#

full_directory#

intersection_error_fn#

left_image_fn#

left_image_sub_fn#

left_mask_fn#

match_point_fn#

orthos#

pairs = []#

right_image_sub_fn#

stereo_directory#

class asp_plot.stereo.StereoPlotter(directory, stereo_directory, dem_gsd=None, dem_fn=None, reference_dem=None, **kwargs)#

Bases: asp_plot.utils.Plotter

Visualize and analyze stereo processing results from ASP.

This class provides methods for plotting and analyzing various outputs from ASP stereo processing, including DEMs, disparity maps, match points, and difference maps with reference DEMs.

directory#

Root directory for ASP processing

Type:: str

stereo_directory#

Directory containing stereo processing outputs

Type:: str

dem_gsd#

Ground sample distance of the DEM in meters

Type:: float or None

dem_fn#

Path to the DEM file

Type:: str or None

reference_dem#

Path to the reference DEM file

Type:: str or None

dem#

DEM data, loaded when needed

Type:: numpy.ma.MaskedArray or None

dem_extent#

Extent of the DEM for plotting

Type:: tuple or None

dem_hs#

Hillshade of the DEM, generated when needed

Type:: numpy.ma.MaskedArray or None

ref_dem#

Reference DEM data, loaded when needed

Type:: numpy.ma.MaskedArray or None

ref_dem_extent#

Extent of the reference DEM for plotting

Type:: tuple or None

dem_diff#

Difference between DEM and reference DEM

Type:: numpy.ma.MaskedArray or None

Examples

>>> plotter = StereoPlotter('/path/to/asp', 'stereo', reference_dem='ref_dem.tif')
>>> plotter.plot_dem_results(save_dir='plots', fig_fn='dem_results.png')
>>> plotter.plot_disparity(save_dir='plots', fig_fn='disparity.png')

get_diff_vs_reference()#

Get the difference between the DEM and a reference DEM.

Tries to find an existing DEM difference file, or generates a difference on-the-fly if a reference DEM is available.

Returns:: Masked array containing the difference between the DEM and reference DEM, or None if no reference DEM is available
Return type:: numpy.ma.MaskedArray or None

Notes

This method first looks for a DEM difference file with a pattern like *diff.tif. If found, it uses that. Otherwise, it computes the difference between the DEM and reference DEM on-the-fly using the Raster.compute_difference method.

get_match_point_df(match_point_fn=None)#

Read a match file into a DataFrame of match points.

Reads the match file produced by ASP stereo processing – the binary .match format or the plain-text format ASP writes with --matches-as-txt (issue #147) – and converts it to a DataFrame containing matched interest points from the left and right images.

Parameters:: match_point_fn (str or None, optional) – Match file to read; defaults to the stereo directory’s top-level match file (a multi-view pair’s match file can be passed instead).
Returns:: DataFrame with columns ‘x1’, ‘y1’, ‘x2’, ‘y2’ representing the coordinates of matched points in the left and right images, or None if the match file doesn’t exist
Return type:: pandas.DataFrame or None

Notes

The format is detected from the file’s bytes rather than its extension (_is_text_match_file()). A binary match file is converted to a CSV file with the same base name but ‘.csv’ extension, then that CSV file is read into a DataFrame; if the CSV file already exists, it is read directly. A plain-text match file is read directly and never consults that cache, so a stale CSV left by an earlier binary run next to it cannot shadow it.

get_vwip_df(vwip_fn)#

Read a per-image raw interest point file (.vwip) into a DataFrame.

These are the interest points ASP detects on each image before matching them across the pair; the .match file keeps only the subset that matched. Comparing the two shows whether sparse matches come from poor matching or from areas with no interest points at all (limited texture, clouds, water).

Parameters:: vwip_fn (str or None) – Path to the .vwip file.
Returns:: DataFrame with columns ‘x’ and ‘y’ of the interest point coordinates, or None if the file is missing.
Return type:: pandas.DataFrame or None

Notes

The file is a single uint64 interest point count followed by the same binary interest point records as the .match file (issue #8).

plot_dem_results(el_clim=None, ie_clim=None, diff_clim=None, save_dir=None, fig_fn=None)#

Plot DEM results with hillshade, error, and difference maps.

Creates a figure with three subplots showing the DEM with hillshade, intersection error, and difference with reference DEM.

Parameters:

el_clim (tuple or None, optional) – Color limits for elevation, default is None (auto)
ie_clim (tuple or None, optional) – Color limits for intersection error, default is None (auto)
diff_clim (tuple or None, optional) – Color limits for difference map, default is None (auto)
save_dir (str or None, optional) – Directory to save the figure, default is None (don’t save)
fig_fn (str or None, optional) – Filename for the saved figure, default is None

Returns:

Displays the plot and optionally saves it

Return type:

None

Notes

This method creates a comprehensive visualization of the stereo DEM results, including: 1. The DEM with hillshade overlay 2. Triangulation intersection error 3. Difference with reference DEM (if available)

If any required files are missing, the corresponding subplot will display a message instead.

plot_detailed_hillshade(intersection_error_percentiles=[16, 50, 84], subset_km=1, clip_windows=None, clip_windows_crs=None, save_dir=None, fig_fn=None)#

Create a detailed plot with DEM hillshade and subsets.

Generates a detailed figure showing the full DEM hillshade with color overlay, plus three smaller subsets highlighting areas with different levels of intersection error. If the images are map-projected, it also shows the corresponding optical image for each subset.

If the intersection error file is missing, it falls back to a plain hillshade plot without the detailed subsets.

The clip boxes that were drawn are recorded on self.detailed_hillshade_clips (a list of {"label", "bbox", "pixel_offset"} dicts, bbox in DEM-CRS map coordinates) so a later run can replay the same clips via clip_windows for run-to-run comparison (issue #121).

Parameters:

intersection_error_percentiles (list, optional) – Percentiles of intersection error to use for selecting subsets, default is [16, 50, 84]
subset_km (float, optional) – Size of the subset areas in kilometers, default is 1
clip_windows (list or None, optional) – When provided, pins the subset clip boxes instead of selecting them from intersection-error variance. A list of up to three map-coordinate bounding boxes [xmin, ymin, xmax, ymax] (as written to a figure-selections file). Boxes that fall outside the current DEM fall back to the automatic selection with a warning. Default is None (automatic selection).
clip_windows_crs (str or None, optional) – CRS the clip_windows bboxes are expressed in. When it differs from the current DEM’s CRS, the boxes are reprojected first so the same ground area is clipped across stereo variants in different projections (e.g. mapprojected vs. non-mapprojected). Default is None (assume the boxes are already in the DEM’s CRS).
save_dir (str or None, optional) – Directory to save the figure, default is None (don’t save)
fig_fn (str or None, optional) – Filename for the saved figure, default is None

Returns:

Displays the plot and optionally saves it

Return type:

None

Notes

This method creates a detailed visualization with a large overview map at the top and six smaller subplots below (three hillshades and three optical images). The subsets are chosen based on the variance of intersection error, representing areas with different quality levels in the DEM.

plot_disparity(unit='pixels', remove_bias=True, quiver=True, save_dir=None, fig_fn=None)#

Plot disparity maps from stereo processing.

Creates a figure with three subplots showing the x and y components of the disparity map and the disparity magnitude, with optional quiver plot overlay.

For a multi-view run, one figure per <prefix>-pairN/ pair is created instead, named <stem>_pairN.png.

Parameters:

unit (str, optional) – Unit for disparity values, either ‘pixels’ or ‘meters’, default is ‘pixels’
remove_bias (bool, optional) – Whether to remove the median offset from disparity values, default is True
quiver (bool, optional) – Whether to overlay a quiver plot on the disparity magnitude plot, default is True
save_dir (str or None, optional) – Directory to save the figure(s), default is None (don’t save)
fig_fn (str or None, optional) – Filename for the saved figure, default is None. For a multi-view run this is the stem the per-pair filenames are derived from.

Returns:

The filename(s) saved (empty if save_dir/fig_fn were not provided).

Return type:

list of str

Raises:

ValueError – If unit is not ‘pixels’ or ‘meters’

Notes

The disparity map shows the pixel offset between corresponding points in the left and right images. This can be displayed in pixel units or converted to meters using the image GSD. The quiver plot shows the direction and magnitude of the disparity vectors.

plot_match_points(save_dir=None, fig_fn=None)#

Plot match points between the left and right images.

Creates a figure with two subplots showing the left and right subsampled images with match points overlaid as small red circles. When the per-image raw interest point files (.vwip) are present, they are underlaid as small blue circles, so sparse matches can be traced to either poor matching or areas with no detected interest points at all (issue #8); if the match file is missing entirely, the raw interest points are still shown on their own. Layers denser than MAX_POINTS_DRAWN are thinned by seeded random sampling for display (the panel titles always report the true counts). For mapprojected scenes, points are rescaled using the GSD ratio. For non-mapprojected scenes, points are transformed from original to aligned coordinate space using the alignment matrices, then rescaled to the subsampled image dimensions.

For a multi-view run, one figure per <prefix>-pairN/ pair is created instead, named <stem>_pairN.png.

Parameters:

save_dir (str or None, optional) – Directory to save the figure(s), default is None (don’t save)
fig_fn (str or None, optional) – Filename for the saved figure, default is None. For a multi-view run this is the stem the per-pair filenames are derived from.

Returns:

The filename(s) saved (empty if save_dir/fig_fn were not provided).

Return type:

list of str

static read_ip_record(match_file)#

Read an interest point record from a binary match file.

Parameters:: match_file (file object) – Open binary match file positioned at the start of an interest point record
Returns:: List containing the interest point record fields, including: - x, y: Floating point coordinates - xi, yi: Integer coordinates - orientation, scale, interest: Feature descriptors - polarity: Boolean flag - octave, scale_lvl: Feature scale information - ndesc: Number of descriptor values - desc: Feature descriptor values
Return type:: list

Notes

This parses the binary ASP match file format, which contains interest points from both images in a stereo pair.

property align_left_fn#

property align_right_fn#

property dem_fn#

property dem_gsd#

property directory#

property disparity_fn#

property disparity_sub_fn#

files#

property full_directory#

property intersection_error_fn#

property left_image_fn#

property left_image_sub_fn#

property left_vwip_fn#

property match_point_fn#

property orthos#

property pairs#

property reference_dem#

property right_image_sub_fn#

property right_vwip_fn#

property stereo_directory#

asp_plot.stereo.read_match_file(match_point_fn)#

Read an ASP match file into a DataFrame of match points.

The binary .match format or the plain-text format ASP writes with --matches-as-txt (issue #147), detected from the file’s bytes rather than its extension. A binary file is converted once to a CSV of the same base name (read directly on later calls); a text file is read directly and never consults that cache, so a stale CSV left by an earlier binary run next to it cannot shadow it.

Needs nothing but the file: a stereo directory whose images have been cleaned up, or a bundle_adjust match file with no stereo run at all, reads the same way. StereoPlotter.get_match_point_df() delegates here.

Parameters:: match_point_fn (str) – Match file to read.
Returns:: Columns ‘x1’, ‘y1’, ‘x2’, ‘y2’: the coordinates of matched points in the first and second image.
Return type:: pandas.DataFrame

asp_plot.stereo.INTEREST_POINT_COLOR = 'deepskyblue'#

asp_plot.stereo.MATCH_POINT_COLOR = 'r'#

asp_plot.stereo.MAX_POINTS_DRAWN = 10000#

asp_plot.stereo.logger#