asp_plot.alignment

asp_plot.alignment#

Attributes#

logger

Classes#

Alignment

Perform DEM alignment using point cloud alignment techniques.

Module Contents#

class asp_plot.alignment.Alignment(directory, dem_fn, **kwargs)#

Perform DEM alignment using point cloud alignment techniques.

This class provides functionality to align DEMs to reference datasets, particularly ICESat-2 ATL06SR altimetry data, using point cloud alignment methods. It includes methods to run the alignment process, extract alignment statistics, and apply the alignment transformation to the DEM.

directory#

Root directory for alignments and outputs

Type:

str

dem_fn#

Path to the DEM file to be aligned

Type:

str

Examples

>>> alignment = Alignment('/path/to/directory', '/path/to/dem.tif')
>>> alignment.pc_align_dem_to_atl06sr(atl06sr_csv='/path/to/icesat2_data.csv')
>>> report = alignment.pc_align_report()
>>> aligned_dem = alignment.apply_dem_translation()
apply_dem_translation(output_prefix='pc_align/pc_align')#

Apply the pc_align translation to the DEM.

Creates a translated version of the DEM by applying the transformation parameters extracted from pc_align log files. This method directly modifies the DEM’s geotransform and pixel values without resampling.

Parameters:

output_prefix (str, optional) – Prefix for pc_align output files, default is “pc_align/pc_align”

Returns:

Path to the translated DEM file

Return type:

str

Raises:

ValueError – If the log file does not contain necessary translation information

Notes

This method is faster and more precise than using point2dem to generate a new DEM from translated point cloud, as it directly applies the translation to the DEM’s metadata and pixel values.

get_proj_shift(src_c, src_shift, s_srs, t_srs, inv_trans=True)#

Calculate projection shift between coordinate systems.

Transforms a shift vector from one coordinate system to another, accounting for the non-linearity of coordinate transformations.

Parameters:

  • src_c (numpy.ndarray) – Source point coordinates in source coordinate system

  • src_shift (numpy.ndarray) – Shift vector in source coordinate system

  • s_srs (osr.SpatialReference) – Source spatial reference system

  • t_srs (osr.SpatialReference) – Target spatial reference system

  • inv_trans (bool, optional) – Whether to invert the transformation direction, default is True

Returns:

Shift vector in target coordinate system

Return type:

numpy.ndarray

Notes

This is a helper method used by apply_dem_translation to convert shifts between coordinate systems. The method handles both same-system transformations and cross-system transformations.

pc_align_dem_to_atl06sr(max_displacement=20, max_source_points=10000000, alignment_method='point-to-point', atl06sr_csv=None, output_prefix='pc_align/pc_align')#

Align DEM to ICESat-2 ATL06SR data using point cloud alignment.

Runs the ASP pc_align tool to align the DEM to ICESat-2 ATL06SR altimetry data. The resulting transformation parameters are saved to log files for later application.

Parameters:

  • max_displacement (float, optional) – Maximum expected displacement in meters, default is 20

  • max_source_points (int, optional) – Maximum number of source points to use, default is 10,000,000

  • alignment_method (str, optional) – Method for alignment, default is “point-to-point”

  • atl06sr_csv (str, optional) – Path to the ATL06SR CSV file, default is None

  • output_prefix (str, optional) – Prefix for output files, default is “pc_align/pc_align”

Raises:

ValueError – If the ATL06SR CSV file is not provided or does not exist

Notes

The ATL06SR CSV file must be formatted with columns for longitude, latitude, and height above datum. This can be created using the to_csv_for_pc_align() function in the Altimetry module.

pc_align_dem_to_planetary_csv(planetary_csv, body, max_displacement=500, max_source_points=10000000, alignment_method='point-to-point', output_prefix='pc_align/pc_align')#

Align DEM to MOLA/LOLA point cloud using pc_align.

Parameters:

  • planetary_csv (str) – Path to a CSV with lon, lat, radius_m columns (planetary radius in meters from the body center). Produced by asp_plot.altimetry.Altimetry.to_csv_for_pc_align_planetary().

  • body (str) – "moon" or "mars" — selects the ASP --datum flag.

  • max_displacement (float, optional) – Maximum expected displacement in meters. ASAP-Stereo’s CTX cookbook recommends ~500 m as a generic default for planetary stereo where absolute pointing is uncertain.

  • max_source_points (int, optional) – Maximum number of source DEM points pc_align will sample.

  • alignment_method (str, optional) – ASP alignment method. Default point-to-point.

  • output_prefix (str, optional) – Prefix for pc_align output files, relative to self.directory.

Notes

Uses --csv-format '1:lon 2:lat 3:radius_m' so pc_align reads the absolute planetary radius and avoids any datum/areoid ambiguity. --datum is set to D_MARS (3,396,190 m) or D_MOON (1,737,400 m) to match ASP DEM heights, which are stored as radius - sphere.

pc_align_report(output_prefix='pc_align/pc_align')#

Extract alignment statistics from pc_align log files.

Parses the pc_align log file to extract error percentiles, translation vectors, and other alignment metrics.

Parameters:

output_prefix (str, optional) – Prefix for pc_align output files, default is “pc_align/pc_align”

Returns:

Dictionary containing alignment metrics: - p16_beg, p50_beg, p84_beg: Error percentiles before alignment - p16_end, p50_end, p84_end: Error percentiles after alignment - north_shift, east_shift, down_shift: Translation vector components

in North-East-Down (NED) coordinate frame, in meters

  • translation_magnitude: Magnitude of translation vector

Return type:

dict

Notes

This method expects the log file to contain specific keyword patterns that match the pc_align output format. If the log format changes, this parser may need to be updated.

The North-East-Down shifts are more interpretable than ECEF (Cartesian) shifts for most applications: - north_shift: Positive = shift northward - east_shift: Positive = shift eastward - down_shift: Positive = shift downward (i.e., DEM is too high)

dem_fn#
directory#
asp_plot.alignment.logger#