ASAP-Stereo¶
ASAP¶
- class asap_stereo.asap.ASAP(https=False, datum='D_MARS')¶
Bases:
object
ASAP Stereo Pipeline
█████████████████████████████████████████████████████████████
/_/ |_/____/_/ |_/_/ 𝑆 𝑇 𝐸 𝑅 𝐸 𝑂
asap_stereo (0.3.1)
Github: https://github.com/AndrewAnnex/asap_stereo Cite: https://doi.org/10.5281/zenodo.4171570
█████████████████████████████████████████████████████████████
- ctx_one(left, right, cwd=None)¶
Run first stage of CTX pipeline
This command runs steps 1-3 of the CTX pipeline
- Parameters:
left – left image id
right – right image id
cwd (
Optional
[str
]) – directory to run process within (default to CWD)
- ctx_three(max_disp=None, demgsd=24, imggsd=6, cwd=None, **kwargs)¶
Run third and final stage of the CTX pipeline
This command runs steps 13-15 of the CTX pipeline
- Parameters:
max_disp (
Optional
[float
]) – Maximum expected displacement in metersdemgsd (
float
) – GSD of final Dem, default is 1 mppimggsd (
float
) – GSD of full res imagecwd (
Optional
[str
]) – directory to run process within (default to CWD)kwargs –
- Return type:
None
- ctx_two(stereo, pedr_list, stereo2=None, cwd=None)¶
Run Second stage of CTX pipeline
This command runs steps 4-12 of the CTX pipeline
- Parameters:
stereo (
str
) – ASP stereo config file to usepedr_list (
str
) – Path to PEDR files, defaults to None to use ODE Rest APIstereo2 (
Optional
[str
]) – 2nd ASP stereo config file to use, if none use first stereo file againcwd (
Optional
[str
]) – directory to run process within (default to CWD)
- Return type:
None
- hirise_one(left, right)¶
Download the EDR data from the PDS, requires two HiRISE Id’s (order left vs right does not matter)
This command runs step 1 of the HiRISE pipeline
- Parameters:
left – HiRISE Id
right – HiRISE Id
- hirise_three(max_disp, ref_dem, demgsd=1, imggsd=0.25, **kwargs)¶
Given estimate of max disparity between reference elevation model and HiRISE output, run point cloud alignment and produce the final DEM/ORTHO data products.
This command runs steps 10-12 of the HiRISE pipeline
- Parameters:
max_disp – Maximum expected displacement in meters
ref_dem – Absolute path the reference dem
demgsd (
float
) – GSD of final Dem, default is 1 mppimggsd (
float
) – GSD of full res image
- Return type:
None
- hirise_two(stereo, mpp=2, bundle_adjust_prefix='adjust/ba', max_iterations=50)¶
Run various calibration steps then: bundle adjust, produce DEM, render low res version for inspection This will take a while (sometimes over a day), use nohup!
This command runs steps 2-9 of the HiRISE pipeline
- Parameters:
stereo – ASP stereo config file to use
mpp – preview DEM GSD, defaults to 2 mpp
bundle_adjust_prefix – bundle adjust prefix, defaults to ‘adjust/ba’
max_iterations – number of iterations for HiRISE bundle adjustment, defaults to 50
- Return type:
None
- info()¶
Get the number of threads and processes as a formatted string
- Returns:
str rep of info
- class asap_stereo.stereo_quality.ImgInfo(path)¶
Bases:
object
- emission_quality()¶
- Return type:
float
- incidence_quality()¶
- Return type:
float
- phase_quality()¶
- Return type:
float
- qualities()¶
- Return type:
tuple
- asap_stereo.stereo_quality.area_overlap(geom1, geom2)¶
Returns a ratio of areas which represent the area of the intersection area of geom1 and geom2, divided by the union of areas of of geom1, and geom2.
- Return type:
float
- asap_stereo.stereo_quality.delta_solar_az_quality(az1, az2)¶
Returns a quality score based on the two solar azimuth values, in degrees.
In practice, Shadow-Tip Distance alone does not guarantee similar illumination. The absolute difference in solar azimuth angle between stereo pairs can be optionally constrained.
Becker et al. (2015) indicates: - Limits: 0° to 100°. - Recommended: ≤ 20°
- Return type:
float
- asap_stereo.stereo_quality.dp(emission1, gndaz1, emission2, gndaz2, radar=False)¶
Returns the Parallax/Height Ratio (dp) as detailed in Becker et al.(2015).
The input angles are assumed to be in radians. If radar is true, then cot() is substituted for tan() in the calculations.
Physically, dp represents the amount of parallax difference that would be measured between an object in the two images, for unit height.
- asap_stereo.stereo_quality.dsh(incidence1, solar_az1, incidence2, solar_az2)¶
Returns the Shadow-Tip Distance (dsh) as detailed in Becker et al.(2015).
The input angles are assumed to be in radians.
This is defined as the distance between the tips of the shadows in the two images for a hypothetical vertical post of unit height. The “shadow length” describes the shadow of a hypothetical pole so it applies whether there are actually shadows in the image or not. It’s a simple and consistent geometrical way to quantify the difference in illumination. This quantity is computed analogously to dp.
- asap_stereo.stereo_quality.emission_quality(emission_angle)¶
Returns a quality score based on the value of emission_angle, which is expected to be in decimal degrees, zero being normal to the surface.
- Return type:
float
Becker et al. (2015) indicates: - Limits: Between 0° and the complement of the maximum slope
(conservatively 45°, greater for smoother terrains) for optical images. Greater than the slope (≥15° even for smooth surfaces) for radar.
Recommended: No recommendation
- asap_stereo.stereo_quality.get_report(file1, file2)¶
Generate the report of the stereo quality :type file1: :param file1: :type file2: :param file2: :rtype:
str
:return:
- asap_stereo.stereo_quality.gsd_quality(gsd1, gsd2)¶
Returns a quality score based on the two ground sample distances, gsd1 and gsd2.
Image pairs with GSD ratios larger than 2.5 can be used but are not optimal, as details only seen in the smaller scale image will be lost. If required, images with ratios greater than ~2.5 should be resampled to the GSD of the lower scale image (Becker at al., 2015).
- Return type:
float
- asap_stereo.stereo_quality.illumination_quality(shadow_tip_distance)¶
Returns a quality score based on the Shadow-Tip Distance (dsh).
Becker et al. (2015) indicates: - Limits: 0 to 2.58. - Recommended: 0
- Return type:
float
- asap_stereo.stereo_quality.incidence_quality(incidence_angle)¶
Returns a quality score based on the value of incidence_angle, which is expected to be in decimal degrees, zero being normal to the surface.
- Return type:
float
Becker et al. (2015) indicates: - Limits: Between 40° and 65° depending on smoothness
(shadows to be avoided).
Recommended: Nominally 50°
- asap_stereo.stereo_quality.parallax(emission1, gndaz1, emission2, gndaz2)¶
Returns the parallax angle between the two look vectors described by the emission angles and sub-spacecraft ground azimuth angles.
Input angles are assumed to be radians, as is the return value.
- Return type:
float
- asap_stereo.stereo_quality.phase_quality(phase_angle)¶
Returns a quality score based on the value of phase_angle, which is expected to be in decimal degrees, zero being normal to the surface.
Becker et al. (2015) indicates: - Limits: Between 5° and 120°. - Recommended: ≥ 30°
- Return type:
float
- asap_stereo.stereo_quality.quality(value, ideal, low, high)¶
Return a quality value based on value.
The value of ideal would be a perfect value of value, but if value is between low and high it is acceptable. ideal must be between low and high, otherwise a ValueError is raised.
A quality value of one indicates that value is ideal. Quality values between zero and one indicate that value is between low and high (the closer to ideal, the higher the quality score). Values less than zero are beyond the acceptable range of low and high.
If ideal is a two-tuple, then this indicates that all values between and including those values are “ideal” values. Again, these two values must be between low and high
- Return type:
float
- asap_stereo.stereo_quality.stereo_overlap_quality(area_fraction)¶
Returns a quality score based on the stereo area overlap.
Becker et al. (2015) indicates: - Limits: Between 30% and 100%. - Recommended: 50% to 100%.
- Return type:
float
- asap_stereo.stereo_quality.stereo_strength_quality(parallax_height_ratio)¶
Returns a quality score based on the Parallax/Height Ratio (dp).
Becker et al. (2015) indicates: - Limits: Between 0.1 (5°) and 1 (~45°). - Recommended: 0.4 (20°) to 0.6 (30°).
- Return type:
float
ASAP (module level)¶
- asap.cmd_to_string()¶
Converts the running command into a single string of the full command call for easier logging
- Parameters:
command (
RunningCommand
) – a command from sh.py that was run- Return type:
str
- Returns:
string of bash command
- @asap_stereo.asap.rich_logger(func)¶
rich logger decorator, wraps a function and writes nice log statements
- Parameters:
func (
Callable
) – function to wrap- Returns:
wrapped function
- asap.par_do(all_calls_args)¶
Parallel execution helper function for sh.py Commands
- Parameters:
func – func to call
all_calls_args – args to pass to each call of the func
- Returns:
list of called commands
CommonSteps¶
- class asap_stereo.asap.CommonSteps¶
Bases:
object
ASAP Stereo Pipeline - Common Commands
█████████████████████████████████████████████████████████████
/_/ |_/____/_/ |_/_/ 𝑆 𝑇 𝐸 𝑅 𝐸 𝑂
asap_stereo (0.3.1)
Github: https://github.com/AndrewAnnex/asap_stereo Cite: https://doi.org/10.5281/zenodo.4171570
█████████████████████████████████████████████████████████████
- bundle_adjust(*vargs, postfix='_RED.cub', bundle_adjust_prefix='adjust/ba', camera_postfix='.json', **kwargs)¶
Bundle adjustment wrapper
#TODO: make function that attempts to find absolute paths to vargs if they are files?
- Parameters:
vargs – any number of additional positional arguments (including GCPs)
postfix – postfix of images to bundle adjust
camera_postfix – postfix for cameras to use
bundle_adjust_prefix – where to save out bundle adjust results
kwargs – kwargs to pass to bundle_adjust
- Return type:
RunningCommand
- Returns:
RunningCommand
- static cam_test(cub, camera, sample_rate=1000, subpixel_offset=0.25)¶
- Return type:
str
- check_mpp_against_true_gsd(path, mpp)¶
Get the GSD of the image, and warn if it is less than 3 * the gsd
- Parameters:
path – path to image
mpp – proposed mpp for image
- compute_footprints(*imgs)¶
for each footprint generate a vector footprint :type imgs: :param imgs: gdal rasters with nodata defined :return:
- static create_stereodirs()¶
- static create_stereodirs_lis()¶
- static create_stereopair_lis()¶
- static create_stereopairs_lis()¶
- crop_by_buffer(ref, src, img_out=None, factor=2.0)¶
use gdal warp to crop img2 by a buffer around img1
- Parameters:
ref – first image defines buffer area
src – second image is cropped by buffer from first
factor – factor to buffer with
- defaults_ps1 = {'--bundle-adjust-prefix': 'adjust/ba', '--processes': 1, '--stop-point': 5, '--threads-multiprocess': 1, '--threads-singleprocess': 2}¶
- defaults_ps2 = {'--bundle-adjust-prefix': 'adjust/ba', '--entry-point': 5, '--processes': 2, '--threads-multiprocess': 1, '--threads-singleprocess': 2}¶
- defaults_ps_s0 = {'--bundle-adjust-prefix': 'adjust/ba', '--entry-point': 0, '--processes': 1, '--stop-point': 1, '--threads-multiprocess': 1, '--threads-singleprocess': 2}¶
- defaults_ps_s1 = {'--bundle-adjust-prefix': 'adjust/ba', '--entry-point': 1, '--processes': 1, '--stop-point': 2, '--threads-multiprocess': 1, '--threads-singleprocess': 2}¶
- defaults_ps_s2 = {'--bundle-adjust-prefix': 'adjust/ba', '--entry-point': 2, '--processes': 1, '--stop-point': 3, '--threads-multiprocess': 1, '--threads-singleprocess': 2}¶
- defaults_ps_s3 = {'--bundle-adjust-prefix': 'adjust/ba', '--entry-point': 3, '--processes': 1, '--stop-point': 4, '--threads-multiprocess': 1, '--threads-singleprocess': 2}¶
- defaults_ps_s4 = {'--bundle-adjust-prefix': 'adjust/ba', '--entry-point': 4, '--processes': 1, '--stop-point': 5, '--threads-multiprocess': 1, '--threads-singleprocess': 2}¶
- defaults_ps_s5 = {'--bundle-adjust-prefix': 'adjust/ba', '--entry-point': 5, '--processes': 2, '--threads-multiprocess': 1, '--threads-singleprocess': 2}¶
- static drg_to_cog(img, scale_bound=0.001, gdal_options=None)¶
- estimate_max_disparity(ref_dem, src_dem=None)¶
Estimate the absolute value of the maximum observed displacement between two point clouds, and the standard deviation of the differences
if not applying an initial transform to pc_align, use the max_d value if expecting to apply a transform first and you are interested in the maximum displacement after an initial transform, then use the std_d returned (likely 3X it)
- estimate_median_disparity(ref_dem, src_dem=None)¶
- static gen_csm(*cubs, meta_kernal=None, max_workers=2)¶
Given N cub files, generate json camera models for each using ale
- generate_csm(postfix='_RED.cub', camera_postfix='_RED.json')¶
generate CSM models for both images :type postfix: :param postfix: :type camera_postfix: :param camera_postfix: :return:
- geoid_adjust(run, output_folder, **kwargs)¶
Adjust DEM to geoid
Run geoid adjustment on dem for final science ready product :type run: :param run: :type output_folder: :param output_folder: :type kwargs: :param kwargs:
- static get_cam_info(img)¶
Get the camera information dictionary from ISIS using camrange
- Parameters:
img – path to image as a string
- Return type:
Dict
- Returns:
dictionary of info
- get_geo_diff(ref_dem, src_dem=None)¶
- static get_image_band_stats(img)¶
- Parameters:
img –
- Return type:
dict
- Returns:
- static get_image_gsd(img, opinion='lower')¶
- Return type:
float
- static get_img_bounds(img)¶
Get the bounds of the image
uses rasterio :type img: :param img: path to image :return: bounds tuple
- static get_img_crs(img)¶
Get CRS of the image
uses rasterio :type img: :param img: path to image :return: CRX of image
- static get_map_info(img, key, group='UniversalGroundRange')¶
- Return type:
str
- static get_mpp_postfix(mpp)¶
get the mpp postfix
- Parameters:
mpp (
Union
[int
,float
,str
]) – mpp value- Return type:
str
- Returns:
postfix as a string
- get_pedr_4_pcalign_common(postfix, proj, https, pedr_list=None)¶
- Return type:
str
- get_pedr_4_pcalign_w_moody(cub_path, proj=None, https=True)¶
Python replacement for pedr_bin4pc_align.sh that uses moody and the PDS geosciences node REST API
- Parameters:
proj – optional projection override
https – optional way to disable use of https
cub_path – path to input file to get query geometry
- Return type:
str
- static get_srs_info(img, use_eqc=None)¶
- Return type:
str
- static get_stereo_quality_report(cub1, cub2)¶
Get the stereo quality report for two cub files The cub files must be Level1 images (Spiceinit’ed but not map-projected).
The quality values reported by this program are based on the recommendations and limitations in Becker et al. (2015). They have a value of one for an ideal value, between zero and one for a value within the acceptable limits, and less than zero (the more negative, the worse) if the value is beyond the acceptable limit. # TODO refactor into more granular bits :type cub1: :param cub1: path :type cub2: :param cub2: path :rtype:
str
:return:
- mapproject_both(refdem=None, mpp=6, postfix='.lev1eo.cub', camera_postfix='.lev1eo.json', bundle_adjust_prefix='adjust/ba', **kwargs)¶
Mapproject the left and right images against a reference DEM
- Parameters:
refdem – reference dem to map project using
mpp – target GSD
postfix – postfix for cub files to use
camera_postfix – postfix for cameras to use
bundle_adjust_prefix – where to save out bundle adjust results
- static parse_stereopairs()¶
- point_cloud_align(datum, maxd=None, refdem=None, highest_accuracy=True, run='results_ba', kind='map_ba_align', **kwargs)¶
- point_to_dem(mpp, pc_suffix, just_ortho=False, just_dem=False, use_proj=None, postfix='.lev1eo.cub', run='results_ba', kind='map_ba_align', output_folder='dem', reference_spheroid='mars', **kwargs)¶
- projections = {'IAU_Mars': '+proj=eqc +lat_ts=0 +lat_0=0 +lon_0=0 +x_0=0 +y_0=0 +a=3396190 +b=3396190 +units=m +no_defs', 'IAU_Mercury': '+proj=eqc +lat_ts=0 +lat_0=0 +lon_0=0 +x_0=0 +y_0=0 +a=2439700 +b=2439700 +units=m +no_defs', 'IAU_Moon': '+proj=eqc +lat_ts=0 +lat_0=0 +lon_0=0 +x_0=0 +y_0=0 +a=1737400 +b=1737400 +units=m +no_defs'}¶
- rescale_and_overwrite(factor, postfix='.lev1eo.cub')¶
Rescale the left and right images
- Parameters:
factor – factor to reduce each dimension by
postfix – file postfix
- rescale_cub(src_file, factor=4, overwrite=False, dst_file=None)¶
rescale an ISIS3 cub file using the ‘reduce’ command given a factor, optionaly do not overwrite file
- Parameters:
src_file (
str
) – path to src cub filefactor – reduction factor (number [lines, samples] / factor)
overwrite – if true overwrite the src file
dst_file – destination file name, append rescaled_ if not specified
- stereo_asap(stereo_conf, refdem='', postfix='.lev1eo.cub', camera_postfix='.json', run='results_ba', output_file_prefix='${run}/${both}_ba', posargs='', **kwargs)¶
parallel stereo common step
- Parameters:
run – stereo run output folder prefix
output_file_prefix – template string for output file prefix
refdem (
str
) – optional reference DEM for 2nd pass stereoposargs (
str
) – additional positional argspostfix – postfix(s) to use for input images
camera_postfix – postfix for cameras to use
stereo_conf (
str
) – stereo config filekwargs – keyword arguments for parallel_stereo
- transform_bounds_and_buffer(img1, img2, factor=2.0)¶
Get bounds of img2 based on centroid of img1 surrounded by a buffer the size of the maximum dimension of img1 (scaled by a factor)
ie if img1 is hirise and img2 is ctx, we find the center point of img1 in img2 then create a bounding box that is buffered (in radius) by the height of the hirise image technically the buffered box would be 2x the height of the hirise which is fine
- Parameters:
img1 – img to find the bounds in img2 space
img2 – crs we are interested in finding the expanded bounds of img1 in
factor – how big we want it (radius is longest dim in img1)
- Returns:
xmin_img2, ymin_img2, xmax_img2, ymax_img2
CTX¶
- class asap_stereo.asap.CTX(https=False, datum='D_MARS', proj=None)¶
Bases:
object
ASAP Stereo Pipeline - CTX workflow
█████████████████████████████████████████████████████████████
/_/ |_/____/_/ |_/_/ 𝑆 𝑇 𝐸 𝑅 𝐸 𝑂
asap_stereo (0.3.1)
Github: https://github.com/AndrewAnnex/asap_stereo Cite: https://doi.org/10.5281/zenodo.4171570
█████████████████████████████████████████████████████████████
- generate_ctx_pair_list(one, two)¶
- get_ctx_emission_angle(pid)¶
- get_ctx_order(one, two)¶
- get_first_pass_refdem(run='results_ba')¶
- Return type:
str
- get_full_ctx_id(pid)¶
- static notebook_pipeline_make_dem(left, right, config1, pedr_list=None, downsample=None, working_dir='./', config2=None, dem_gsd=24.0, img_gsd=6.0, max_disp=None, step_kwargs=None, out_notebook=None, **kwargs)¶
First step in CTX DEM pipeline that uses papermill to persist log
this command does most of the work, so it is long running! I recommend strongly to use nohup with this command
- Parameters:
out_notebook – output notebook log file name, defaults to log_asap_notebook_pipeline_make_dem.ipynb
config2 (
Optional
[str
]) – ASP config file to use for second processing passworking_dir – Where to execute the processing, defaults to current directory
config1 (
str
) – ASP config file to use for first processing passpedr_list (
Optional
[str
]) – Path to PEDR files, defaults to None to use ODE Rest APIleft (
str
) – First image idright (
str
) – Second image idmax_disp – Maximum expected displacement in meters, use None to determine it automatically
step_kwargs – Arbitrary dict of kwargs for steps following {‘step_#’ : {‘key’: ‘value}}
downsample (
Optional
[int
]) – Factor to downsample images for faster productiondem_gsd – desired GSD of output DEMs (4x image GSD)
img_gsd – desired GSD of output ortho images
kwargs – kwargs for papermill
- step_1(one, two, cwd=None)¶
Download CTX EDRs from the PDS
- Parameters:
one (
str
) – first CTX image idtwo (
str
) – second CTX image idcwd (
Optional
[str
]) –
- Return type:
None
- step_10(stereo_conf, refdem=None, posargs='', postfix='.ba.map.tif', camera_postfix='.lev1eo.json', **kwargs)¶
Second stereo first step
- Parameters:
stereo_conf –
refdem – path to reference DEM or PEDR csv file
posargs – additional positional args
postfix – postfix for files to use
camera_postfix – postfix for cameras to use
kwargs –
- step_11(stereo_conf, refdem=None, posargs='', postfix='.ba.map.tif', camera_postfix='.lev1eo.json', **kwargs)¶
Second stereo second step
- Parameters:
stereo_conf –
refdem – path to reference DEM or PEDR csv file
posargs – additional positional args
postfix – postfix for files to use
camera_postfix – postfix for cameras to use
kwargs –
- step_12(pedr_list=None, postfix='.lev1eo')¶
Get MOLA PEDR data to align the CTX DEM to
- Parameters:
postfix – postfix for file, minus extension
pedr_list – path local PEDR file list, default None to use REST API
- step_13(run='results_map_ba', maxd=None, refdem=None, highest_accuracy=True, **kwargs)¶
PC Align CTX
Run pc_align using provided max disparity and reference dem optionally accept an initial transform via kwargs
- Parameters:
run – folder used for this processing run
highest_accuracy – Use the maximum accuracy mode
maxd (
Optional
[float
]) – Maximum expected displacement in metersrefdem – path to pedr csv file or reference DEM/PC, if not provided assume pedr4align.csv is available
kwargs –
- step_14(mpp=24.0, just_ortho=False, run='results_map_ba', output_folder='dem_align', postfix='.lev1eo.cub', **kwargs)¶
Produce final DEMs/Orthos
Run point2dem on the aligned output to produce final science ready products
- Parameters:
run – folder used for this processing run
mpp –
just_ortho –
output_folder –
postfix – postfix for cub files to use
kwargs –
- step_15(run='results_map_ba', output_folder='dem_align', **kwargs)¶
Adjust DEM to geoid
Run geoid adjustment on dem for final science ready product :type run: :param run: folder used for this processing run :type output_folder: :param output_folder: :type kwargs: :param kwargs:
- step_2(with_web=False)¶
ISIS3 CTX preprocessing, replaces ctxedr2lev1eo.sh
- Parameters:
with_web – if true attempt to use webservices for SPICE kernel data
- step_3()¶
Create various processing files for future steps # todo: deduplicate with hirise side
- step_4(*vargs, bundle_adjust_prefix='adjust/ba', postfix='.lev1eo.cub', camera_postfix='.lev1eo.json', **kwargs)¶
Bundle Adjust CTX
Run bundle adjustment on the CTX map projected data
- Parameters:
vargs – variable length additional positional arguments to pass to bundle adjust
bundle_adjust_prefix – prefix for bundle adjust output
postfix – postfix for cub files to use
camera_postfix – postfix for cameras
- Return type:
RunningCommand
- step_5(stereo_conf, posargs='', postfix='.lev1eo.cub', camera_postfix='.lev1eo.json', **kwargs)¶
Parallel Stereo Part 1
Run first part of parallel_stereo asp_ctx_lev1eo2dem.sh
- Parameters:
postfix – postfix for cub files to use
camera_postfix – postfix for cameras # TODO: use .adjusted_state.json?
- step_6(stereo_conf, posargs='', postfix='.lev1eo.cub', camera_postfix='.lev1eo.json', **kwargs)¶
Parallel Stereo Part 2
Run second part of parallel_stereo, asp_ctx_lev1eo2dem.sh stereo is completed after this step
- Parameters:
postfix – postfix for cub files to use
camera_postfix – postfix for cameras # TODO: use .adjusted_state.json?
- step_7(mpp=24, just_ortho=False, run='results_ba', postfix='.lev1eo.cub', **kwargs)¶
Produce preview DEMs/Orthos
Produce dem from point cloud, by default 24mpp for ctx for max-disparity estimation
- Parameters:
run – folder for results
just_ortho – set to True if you only want the ortho image, else make dem and error image
mpp – resolution in meters per pixel
postfix – postfix for cub files to use
- step_8(run='results_ba', output_folder='dem')¶
hillshade First step in asp_ctx_step2_map2dem script
- Parameters:
output_folder –
run –
mpp –
- step_9(refdem=None, mpp=6, run='results_ba', postfix='.lev1eo.cub', camera_postfix='.lev1eo.json')¶
Mapproject the left and right ctx images against the reference DEM
- Parameters:
run – name of run
refdem – reference dem to map project using
mpp – target GSD
postfix – postfix for cub files to use
camera_postfix – postfix for cameras to use
HiRISE¶
- class asap_stereo.asap.HiRISE(https=False, datum='D_MARS', proj=None)¶
Bases:
object
ASAP Stereo Pipeline - HiRISE workflow
█████████████████████████████████████████████████████████████
/_/ |_/____/_/ |_/_/ 𝑆 𝑇 𝐸 𝑅 𝐸 𝑂
asap_stereo (0.3.1)
Github: https://github.com/AndrewAnnex/asap_stereo Cite: https://doi.org/10.5281/zenodo.4171570
█████████████████████████████████████████████████████████████
- generate_hirise_pair_list(one, two)¶
Generate the hirise pair.lis file for future steps
- Parameters:
one – first image id
two – second image id
- get_hirise_emission_angle(pid)¶
Use moody to get the emission angle of the provided HiRISE image id
- Parameters:
pid (
str
) – HiRISE image id- Return type:
float
- Returns:
emission angle
- get_hirise_order(one, two)¶
Get the image ids sorted by lower emission angle
- Parameters:
one (
str
) – first imagetwo (
str
) – second image
- Return type:
Tuple
[str
,str
]- Returns:
tuple of sorted images
- static notebook_pipeline_make_dem(left, right, config, ref_dem, gcps='', max_disp=None, downsample=None, dem_gsd=1.0, img_gsd=0.25, max_ba_iterations=200, alignment_method='rigid', step_kwargs=None, working_dir='./', out_notebook=None, **kwargs)¶
First step in HiRISE DEM pipeline that uses papermill to persist log
This command does most of the work, so it is long running! I recommend strongly to use nohup with this command, even more so for HiRISE!
- Parameters:
out_notebook – output notebook log file name, defaults to log_asap_notebook_pipeline_make_dem_hirise.ipynb
working_dir – Where to execute the processing, defaults to current directory
config (
str
) – ASP config file to use for processingleft (
str
) – first image idright (
str
) – second image idalignment_method – alignment method to use for pc_align
downsample (
Optional
[int
]) – Factor to downsample images for faster productionref_dem (
str
) – path to reference DEM or PEDR csv filegcps (
str
) – path to gcp file todo: currently only one gcp file allowedmax_disp (
Optional
[float
]) – Maximum expected displacement in meters, specify none to determine it automaticallydem_gsd (
float
) – desired GSD of output DEMs (4x image GSD)img_gsd (
float
) – desired GSD of output ortho imagesmax_ba_iterations (
int
) – maximum number of BA steps to use per run (defaults to 50 for slow running hirise BA)step_kwargs – Arbitrary dict of kwargs for steps following {‘step_#’ : {‘key’: ‘value}}
- pre_step_10(refdem, run='results_ba', alignment_method='translation', do_resample='gdal', **kwargs)¶
Hillshade Align before PC Align
Automates the procedure to use ipmatch on hillshades of downsampled HiRISE DEM to find an initial transform
- Parameters:
run –
do_resample – can be: ‘gdal’ or ‘asp’ or anything else for no resampling
alignment_method – can be ‘similarity’ ‘rigid’ or ‘translation’
refdem – path to reference DEM or PEDR csv file
kwargs –
- pre_step_10_pedr(pedr_list=None, postfix='_RED.cub')¶
Use MOLA PEDR data to align the HiRISE DEM to in case no CTX DEM is available
- Parameters:
pedr_list – path local PEDR file list, default None to use REST API
postfix – postfix for cub files to use
- Return type:
str
- step_1(one, two, cwd=None)¶
Download HiRISE EDRs
Download two HiRISE images worth of EDR files to two folders
- Parameters:
one – first image id
two – second image id
cwd (
Optional
[str
]) –
- step_10(maxd, refdem, run='results_ba', highest_accuracy=True, **kwargs)¶
PC Align HiRISE
Run pc_align using provided max disparity and reference dem optionally accept an initial transform via kwargs
- Parameters:
run –
maxd – Maximum expected displacement in meters
refdem – path to reference DEM or PEDR csv file
highest_accuracy – use highest precision alignment (more memory and cpu intensive)
kwargs – kwargs to pass to pc_align, use to override ASAP defaults
- step_11(mpp=1.0, just_ortho=False, postfix='_RED.cub', run='results_ba', output_folder='dem_align', **kwargs)¶
Produce final DEMs/Orthos
Run point2dem on the aligned output to produce final science ready products
- Parameters:
run –
postfix – postfix for cub files to use
mpp – Desired GSD (meters per pixel)
just_ortho – if True, just render out the ortho images
output_folder – output folder name
kwargs – any other kwargs you want to pass to point2dem
- step_12(run='results_ba', output_folder='dem_align', **kwargs)¶
Adjust DEM to geoid
Run geoid adjustment on dem for final science ready product
- Parameters:
run –
output_folder –
kwargs –
- step_2()¶
Metadata init
Create various files with info for later steps
- step_3()¶
Hiedr2mosaic preprocessing
Run hiedr2mosaic on all the data
- step_4(postfix='*.mos_hijitreged.norm.cub', camera_postfix='_RED.json')¶
Copy hieder2mosaic files
Copy the hiedr2mosaic output to the location needed for cam2map4stereo
- Parameters:
postfix – postfix for cub files to use
- step_5(refdem=None, gsd=None, postfix='_RED.cub', camera_postfix='_RED.json', bundle_adjust_prefix=None, **kwargs)¶
# todo this no longer makes sense for step 5, needs to run after bundle adjust but before stereo # todo need cameras by this point, currently done in BA Map project HiRISE data for stereo processing
Note this step is optional.
- Parameters:
bundle_adjust_prefix –
camera_postfix –
postfix – postfix for cub files to use
gsd (
Optional
[float
]) – override for final resolution in meters per pixel (mpp)
- step_6(*vargs, postfix='_RED.cub', camera_postfix='_RED.json', bundle_adjust_prefix='adjust/ba', **kwargs)¶
Bundle Adjust HiRISE
Run bundle adjustment on the HiRISE map projected data
- Parameters:
postfix – postfix for cub files to use
camera_postfix – postfix for cameras to use
vargs – variable length additional positional arguments to pass to bundle adjust
bundle_adjust_prefix –
- Return type:
RunningCommand
- step_7(stereo_conf, postfix='_RED.cub', camera_postfix='_RED.json', run='results_ba', posargs='', **kwargs)¶
Parallel Stereo Part 1
Run first part of parallel_stereo
- Parameters:
run – folder for results of run
postfix – postfix for cub files to use
camera_postfix – postfix for cameras to use
- step_8(stereo_conf, postfix='_RED.cub', camera_postfix='_RED.json', run='results_ba', posargs='', **kwargs)¶
Parallel Stereo Part 2
Run second part of parallel_stereo, stereo is completed after this step
- Parameters:
run – folder for results of run
postfix – postfix for cub files to use
camera_postfix – postfix for cameras to use
- step_9(mpp=2, just_dem=True, postfix='_RED.cub', run='results_ba', **kwargs)¶
Produce preview DEMs/Orthos
Produce dem from point cloud, by default 2mpp for hirise for max-disparity estimation
- Parameters:
run – folder for results of run
postfix – postfix for cub files to use
just_dem – set to True if you only want the DEM and no other products like the ortho and error images
mpp –
Georef¶
- class asap_stereo.asap.Georef¶
Bases:
object
ASAP Stereo Pipeline - Georef Tools
█████████████████████████████████████████████████████████████
/_/ |_/____/_/ |_/_/ 𝑆 𝑇 𝐸 𝑅 𝐸 𝑂
asap_stereo (0.3.1)
Github: https://github.com/AndrewAnnex/asap_stereo Cite: https://doi.org/10.5281/zenodo.4171570
█████████████████████████████████████████████████████████████
- add_gcps(gcp_csv_file, mobile_file)¶
Given a gcp file in csv format (can have Z values or different extension) use gdaltranslate to add the GCPs to the provided mobile file by creating a VRT raster
- create_gcps(reference_image, match_file_csv, out_name=None)¶
Given a reference image and a match file in csv format, generate a csv of GCPs. By default just prints to stdout but out_name allows you to name the csv file or you can pipe
- find_matches(reference_image, *mobile_images, ipfindkwargs=None, ipmatchkwargs=None)¶
Generate GCPs for a mobile image relative to a reference image and echo to std out #todo: do we always assume the mobile_dem has the same srs/crs and spatial resolution as the mobile image? #todo: implement my own normalization :type reference_image: :param reference_image: reference vis image :type mobile_images: :param mobile_images: image we want to move to align to reference image :type ipfindkwargs: :param ipfindkwargs: override kwargs for ASP ipfind :type ipmatchkwargs: :param ipmatchkwargs: override kwarge for ASP ipmatch :return:
- get_common_matches(ref_left_match, ref_right_match)¶
returns coordinates as column row (x, y). rasterio xy expects row column
- get_ref_z(common_ref_left_crs, ref_dem)¶
- im_feeling_lucky(ref_img, mobile_image, *other_mobile, ipfindkwargs=None, ipmatchkwargs=None, gdal_warp_args=None)¶
Georeference an mobile dataset against a reference image. Do it all in one go, can take N mobile datasets but assumes the first is the mobile image. If unsure normalize your data ahead of time
- make_ba_gcps(ref_img, ref_dem, ref_left_match, ref_right_match, left_name, lr_left_name, right_name, lr_right_name, eoid='+proj=longlat +R=3396190 +no_defs', out_name=None)¶
- make_gcps_for_ba(ref_img, ref_dem, left, right, eoid='+proj=longlat +R=3396190 +no_defs', out_name=None, ipfindkwargs=None)¶
- Given a reference image and dem, and two images for a stereopair,
automatically create GCPs for ASP’s BA by finding ip match points common between the reference image and the left and right images for the new pair and sampling the z values from the reference DEM.
note that this will create several vrt files because we want to make normalized downsampled images to find a good number of matches and to save time between images of large resolution differences
- match_gsds(ref_image, *images)¶
- matches_to_csv(match_file)¶
Convert an ASP .match file from ipmatch to CSV
- normalize(image)¶
- ref_in_crs(common, ref_img, cr=True)¶
- transform_matches(match_file_csv, mobile_img, mobile_other, outname=None)¶
Given a csv match file of two images (reference and mobile), and a third image (likely a DEM) create a modified match csv file with the coordinates transformed for the 2nd (mobile) image This works using the CRS of the images and assumes that both mobile images are already co-registered This is particularly useful when the imagery is higher pixel resolution than a DEM, and permits generating duplicated gcps
- static warp(reference_image, mobile_vrt, out_name=None, gdal_warp_args=None, tr=1.0)¶
Final step in workflow, given a reference image and a mobile vrt with attached GCPs use gdalwarp to create a modified non-virtual file that is aligned to the reference image