asp_plot.stereo

Contents

asp_plot.stereo#

Attributes#

logger

Classes#

StereoFiles

Discover the ASP stereo output files for a processing directory.

StereoPlotter

Visualize and analyze stereo processing results from ASP.

Module Contents#

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

is_vantor#

Whether the source imagery is from a Vantor-owned satellite (WorldView family, GeoEye, QuickBird, etc.); gates the “© Vantor” copyright overlay.

Type:

bool

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

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 (the non--disp- one when several exist).

Type:

str

disparity_sub_fn, disparity_fn

Sub-sampled and full disparity map paths.

Type:

str or None

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

align_left_fn#
align_right_fn#
dem_gsd = None#
directory#
disparity_fn#
disparity_sub_fn#
full_directory#
intersection_error_fn#
is_vantor = False#
left_image_fn#
left_image_sub_fn#
match_point_fn#
orthos = False#
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()#

Convert a binary match file to a DataFrame of match points.

Reads the binary match file produced by ASP stereo processing and converts it to a DataFrame containing matched interest points from the left and right images.

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

This method converts the binary match file to a CSV file with the same base name but ‘.csv’ extension, then reads that CSV file into a DataFrame. If the CSV file already exists, it is read directly.

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.

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, 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

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. For mapprojected scenes, match points are rescaled using the GSD ratio. For non-mapprojected scenes, match points are transformed from original to aligned coordinate space using the alignment matrices, then rescaled to the subsampled image dimensions.

Parameters:

  • 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

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 method is used to parse 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 match_point_fn#
property orthos#
property reference_dem#
property right_image_sub_fn#
property stereo_directory#
asp_plot.stereo.logger#
Contents