asp_plot.alignment ================== .. py:module:: asp_plot.alignment Attributes ---------- .. autoapisummary:: asp_plot.alignment.logger Classes ------- .. autoapisummary:: asp_plot.alignment.Alignment Module Contents --------------- .. py:class:: 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. .. attribute:: directory Root directory for alignments and outputs :type: str .. attribute:: dem_fn Path to the DEM file to be aligned :type: str .. rubric:: 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() .. py:method:: 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. :param output_prefix: Prefix for pc_align output files, default is "pc_align/pc_align" :type output_prefix: str, optional :returns: Path to the translated DEM file :rtype: str :raises ValueError: If the log file does not contain necessary translation information .. rubric:: 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. .. py:method:: 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. :param src_c: Source point coordinates in source coordinate system :type src_c: numpy.ndarray :param src_shift: Shift vector in source coordinate system :type src_shift: numpy.ndarray :param s_srs: Source spatial reference system :type s_srs: osr.SpatialReference :param t_srs: Target spatial reference system :type t_srs: osr.SpatialReference :param inv_trans: Whether to invert the transformation direction, default is True :type inv_trans: bool, optional :returns: Shift vector in target coordinate system :rtype: numpy.ndarray .. rubric:: 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. .. py:method:: 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. :param max_displacement: Maximum expected displacement in meters, default is 20 :type max_displacement: float, optional :param max_source_points: Maximum number of source points to use, default is 10,000,000 :type max_source_points: int, optional :param alignment_method: Method for alignment, default is "point-to-point" :type alignment_method: str, optional :param atl06sr_csv: Path to the ATL06SR CSV file, default is None :type atl06sr_csv: str, optional :param output_prefix: Prefix for output files, default is "pc_align/pc_align" :type output_prefix: str, optional :raises ValueError: If the ATL06SR CSV file is not provided or does not exist .. rubric:: 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. .. py:method:: 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. :param planetary_csv: Path to a CSV with ``lon``, ``lat``, ``radius_m`` columns (planetary radius in meters from the body center). Produced by :meth:`asp_plot.altimetry.Altimetry.to_csv_for_pc_align_planetary`. :type planetary_csv: str :param body: ``"moon"`` or ``"mars"`` — selects the ASP ``--datum`` flag. :type body: str :param max_displacement: 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. :type max_displacement: float, optional :param max_source_points: Maximum number of source DEM points pc_align will sample. :type max_source_points: int, optional :param alignment_method: ASP alignment method. Default ``point-to-point``. :type alignment_method: str, optional :param output_prefix: Prefix for pc_align output files, relative to ``self.directory``. :type output_prefix: str, optional .. rubric:: 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``. .. py:method:: 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. :param output_prefix: Prefix for pc_align output files, default is "pc_align/pc_align" :type output_prefix: str, optional :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 :rtype: dict .. rubric:: 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) .. py:attribute:: dem_fn .. py:attribute:: directory .. py:data:: logger