asp_plot.bundle_adjust

asp_plot.bundle_adjust#

Attributes#

logger

Classes#

PlotBundleAdjustFiles

Plot bundle adjustment results from GeoDataFrames.

ReadBundleAdjustFiles

Read and process bundle adjustment output files from ASP.

Module Contents#

class asp_plot.bundle_adjust.PlotBundleAdjustFiles(geodataframes, **kwargs)#

Bases: asp_plot.utils.Plotter

Plot bundle adjustment results from GeoDataFrames.

This class extends the base Plotter class to provide specialized plotting functionality for bundle adjustment results. It can create visualizations of residuals, geodiff results, and other bundle adjustment outputs.

geodataframes#

List of GeoDataFrames containing bundle adjustment data to plot

Type:

list of geopandas.GeoDataFrame

title#

Plot title, inherited from Plotter class

Type:

str

Examples

>>> ba_reader = ReadBundleAdjustFiles('/path/to/asp', 'ba')
>>> initial_gdf, final_gdf = ba_reader.get_initial_final_residuals_gdfs()
>>> ba_plotter = PlotBundleAdjustFiles([initial_gdf, final_gdf], title="Bundle Adjustment Residuals")
>>> ba_plotter.plot_n_gdfs(column_name="mean_residual_meters", cbar_label="Mean residual (m)")
gdf_percentile_stats(gdf, column_name='mean_residual')#

Calculate percentile statistics for a GeoDataFrame column.

Computes the 25th, 50th, 84th, and 95th percentiles for a specified column in a GeoDataFrame.

Parameters:

  • gdf (geopandas.GeoDataFrame) – GeoDataFrame to analyze

  • column_name (str, optional) – Column to calculate statistics for, default is “mean_residual”

Returns:

List of statistics at the 25th, 50th, 84th, and 95th percentiles

Return type:

list

Notes

These percentiles are commonly used in remote sensing and photogrammetry to assess error distributions. The 50th percentile is the median, while the 84th percentile is approximately equivalent to one standard deviation in a normal distribution.

plot_n_gdfs(column_name='mean_residual', cbar_label='Mean residual (px)', clip_final=True, clim=None, common_clim=True, symm_clim=False, cmap='inferno', map_crs='EPSG:4326', save_dir=None, fig_fn=None, **ctx_kwargs)#

Plot multiple GeoDataFrames in a grid layout.

Creates a figure with multiple subplots, one for each GeoDataFrame in the geodataframes list. Each subplot shows the spatial distribution of the specified column values.

Parameters:

  • column_name (str, optional) – Column to visualize, default is “mean_residual”

  • cbar_label (str, optional) – Label for the colorbar, default is “Mean residual (px)”

  • clip_final (bool, optional) – Whether to clip the final plot to prevent autoscaling, default is True

  • clim (tuple or None, optional) – Color limits as (min, max), default is None (auto)

  • common_clim (bool, optional) – Whether to use the same color limits for all plots, default is True

  • symm_clim (bool, optional) – Whether to use symmetric color limits, default is False

  • cmap (str, optional) – Matplotlib colormap name, default is “inferno”

  • map_crs (str, optional) – Coordinate reference system for plotting, default is “EPSG:4326”

  • 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

  • **ctx_kwargs (dict, optional) – Additional keyword arguments for contextily basemap

Returns:

Displays the plot and optionally saves it

Return type:

None

Notes

Each subplot includes a text box showing statistics for the displayed data, including the number of points and percentile values. The layout automatically adjusts based on the number of GeoDataFrames to plot.

geodataframes#
class asp_plot.bundle_adjust.ReadBundleAdjustFiles(directory, bundle_adjust_directory)#

Read and process bundle adjustment output files from ASP.

This class provides functionality to read and process the outputs from ASP’s bundle_adjust tool, including residual point maps, map-projected residuals, and triangulation uncertainty. It can also generate geodiff files to compare bundle adjustment results with reference DEMs.

directory#

Root directory of ASP processing

Type:

str

bundle_adjust_directory#

Subdirectory containing bundle adjustment outputs

Type:

str

full_directory#

Full path to bundle adjustment directory

Type:

str

Examples

>>> ba_reader = ReadBundleAdjustFiles('/path/to/asp', 'ba')
>>> initial_gdf, final_gdf = ba_reader.get_initial_final_residuals_gdfs()
>>> geodiff_initial, geodiff_final = ba_reader.get_initial_final_geodiff_gdfs()
>>> mapproj_gdf = ba_reader.get_mapproj_residuals_gdf()
generate_geodiff(path)#

Generate geodiff file comparing residuals to a reference DEM.

Uses ASP’s geodiff tool to calculate height differences between bundle adjustment residual points and a reference DEM.

Parameters:

path (str) – Path to the bundle adjustment residual CSV file

Notes

The geodiff output file will be saved with the same name as the input file, but with “-diff.csv” appended. This method requires the geodiff tool from ASP and a reference DEM that was used in the bundle adjustment process.

get_csv_paths(geodiff_files=False)#

Get paths to bundle adjustment residual CSV files.

Finds the paths to the initial and final residual point map CSV files from bundle adjustment. Can optionally find or generate geodiff files comparing these residuals to a reference DEM.

Parameters:

geodiff_files (bool, optional) – Whether to return paths to geodiff files instead of regular residual CSV files, default is False

Returns:

Paths to initial and final residual CSV files or geodiff files

Return type:

tuple of str

Raises:

ValueError – If required bundle adjustment CSV files cannot be found

Notes

If geodiff_files is True and the files don’t exist, this method will attempt to generate them using the geodiff ASP tool.

get_geodiff_gdf(csv_path)#

Read geodiff output into a GeoDataFrame.

Reads a geodiff output CSV file and converts it to a GeoDataFrame with appropriate geometry.

Parameters:

csv_path (str) – Path to the geodiff CSV file

Returns:

GeoDataFrame containing geodiff data with point geometry

Return type:

geopandas.GeoDataFrame

Notes

The returned GeoDataFrame has a ‘filename’ attribute set to the base name of the input file. The main data column is ‘height_diff_meters’, which contains the height differences between residual points and the reference DEM.

get_initial_final_geodiff_gdfs()#

Get both initial and final geodiff results as GeoDataFrames.

A convenience method that combines get_csv_paths() and get_geodiff_gdf() to obtain both initial and final geodiff results.

Returns:

GeoDataFrames containing initial and final geodiff data

Return type:

tuple of geopandas.GeoDataFrame

Notes

This is a convenience method that calls get_csv_paths(geodiff_files=True) and get_geodiff_gdf() for both initial and final geodiff files. If the geodiff files don’t exist, they will be generated using generate_geodiff().

get_initial_final_residuals_gdfs(residuals_in_meters=True)#

Get both initial and final residuals as GeoDataFrames.

A convenience method that combines get_csv_paths() and get_residuals_gdf() to obtain both initial and final bundle adjustment residuals.

Parameters:

residuals_in_meters (bool, optional) – Whether to convert residuals from pixels to meters using the mean GSD from the stereopair metadata, default is True

Returns:

GeoDataFrames containing initial and final residual data

Return type:

tuple of geopandas.GeoDataFrame

Notes

This is a convenience method that calls get_csv_paths() and get_residuals_gdf() for both initial and final residual files.

get_mapproj_residuals_gdf()#

Get map-projected residuals as a GeoDataFrame.

Reads the map-projected match offsets file produced by bundle_adjust and converts it to a GeoDataFrame.

Returns:

GeoDataFrame containing map-projected residual data

Return type:

geopandas.GeoDataFrame

Raises:

ValueError – If the map-projected match offsets file cannot be found

Notes

The main data column is ‘mapproj_ip_dist_meters’, which contains the distance between matched interest points in the map-projected images after bundle adjustment.

get_propagated_triangulation_uncert_df()#

Get propagated triangulation uncertainty as a DataFrame.

Reads the triangulation uncertainty file produced by bundle_adjust, which contains statistics on the expected horizontal and vertical error in the DEM.

Returns:

DataFrame containing triangulation uncertainty data

Return type:

pandas.DataFrame

Raises:

ValueError – If the triangulation uncertainty file cannot be found

Notes

The triangulation uncertainty file contains statistics on how the bundle adjustment residuals propagate to uncertainty in triangulation. This is an estimate of the final DEM error.

get_residuals_gdf(csv_path, residuals_in_meters=True)#

Read bundle adjustment residuals into a GeoDataFrame.

Reads a bundle adjustment residuals CSV file and converts it to a GeoDataFrame with appropriate geometry. Can optionally convert residuals from pixels to meters.

Parameters:

  • csv_path (str) – Path to the residuals CSV file

  • residuals_in_meters (bool, optional) – Whether to convert residuals from pixels to meters using the mean GSD from the stereopair metadata, default is True

Returns:

GeoDataFrame containing residual data with point geometry

Return type:

geopandas.GeoDataFrame

Notes

The returned GeoDataFrame has a ‘filename’ attribute set to the base name of the input file. If residuals_in_meters is True, a new column ‘mean_residual_meters’ will be added with pixel residuals converted to meters.

bundle_adjust_directory#
directory#
full_directory#
asp_plot.bundle_adjust.logger#