instruments.mro.hirise

instruments.mro.hirise

MRO HiRISE instrument support.

Provides browse image download, solar geometry lookup from PDS indexes, and EDR source product management for ISIS processing pipelines.

Examples

>>> from planetarypy.instruments.mro.hirise import get_browse, get_metadata
>>> path = get_browse("ESP_013807_2035_RED")
>>> meta = get_metadata("ESP_013807_2035_RED")
>>> meta["SUB_SOLAR_AZIMUTH"]
129.324

>>> from planetarypy.instruments.mro.hirise import RED_PRODUCT
>>> prod = RED_PRODUCT("ESP_013807_2035", ccdno=4, channel=0)
>>> prod.download()

Classes

Name	Description
RED_PRODUCT	Convenience constructor for RED CCD source products.
SOURCE_PRODUCT	Manage a HiRISE source product (EDR) by its product ID.

RED_PRODUCT

instruments.mro.hirise.RED_PRODUCT(obsid, ccdno, channel, **kwargs)

[source]

Convenience constructor for RED CCD source products.

Parameters

Name	Type	Description	Default
obsid	str	Observation ID, e.g. `"ESP_013807_2035"`.	required
ccdno	int	CCD number (0-9 for RED).	required
channel	int	Channel number (0 or 1).	required

Examples

>>> prod = RED_PRODUCT("ESP_013807_2035", ccdno=4, channel=0)
>>> prod.spid
'ESP_013807_2035_RED4_0'

SOURCE_PRODUCT

instruments.mro.hirise.SOURCE_PRODUCT(spid, saveroot=None, check_url=False)

[source]

Manage a HiRISE source product (EDR) by its product ID.

Handles URL construction, local path management, and download for individual CCD channel EDR files (e.g. PSP_003092_0985_RED4_0).

Parameters

Name	Type	Description	Default
spid	str	Full source product ID, e.g. `"PSP_003092_0985_RED4_0"`.	required
saveroot	Path	Override storage root. Defaults to `~/planetarypy_data/mro/hirise/`.	`None`
check_url	bool	If True, warn when the constructed URL doesn’t exist on the server.	`False`

Examples

>>> prod = SOURCE_PRODUCT("PSP_003092_0985_RED4_0")
>>> prod.obsid
'PSP_003092_0985'
>>> prod.local_path  # ~/planetarypy_data/mro/hirise/PSP_003092_0985/...
PosixPath('.../mro/hirise/PSP_003092_0985/PSP_003092_0985_RED4_0.IMG')

Methods

Name	Description
download	Download the EDR .IMG file from the HiRISE PDS archive.

download

instruments.mro.hirise.SOURCE_PRODUCT.download(overwrite=False, **tqdm_kwargs)

Download the EDR .IMG file from the HiRISE PDS archive.

Parameters

Name	Type	Description	Default
overwrite	bool	Re-download even if cached locally.	`False`
**tqdm_kwargs		Passed to `url_retrieve` (e.g. `tqdm_position`, `leave_tqdm`).	`{}`

[source]

Functions

Name	Description
browse_url	Return the HiRISE EXTRAS browse-JPEG URL for a product ID.
calibrate_channel	Radiometrically calibrate a single HiRISE channel cube.
create_mosaic	Create a HiRISE CCD mosaic from EDR data.
create_mosaics	Create one HiRISE mosaic per requested color.
create_red_mosaic	Convenience wrapper for `create_mosaic(color='red')`.
download_edr	Download HiRISE EDR channel files for an observation.
edr_products	Build a list of EDR SOURCE_PRODUCTs for an observation.
format_meta	Shape a HiRISE meta row for `plp meta` / `get_meta`.
get_browse	Download a HiRISE browse JPEG and return its local path.
get_metadata	Look up HiRISE metadata from the PDS index.
ingest_edr	Convert a HiRISE EDR .IMG to an ISIS cube and initialize SPICE.
map_project	Map-project a calibrated, normalized CCD cube.
stitch_channels	Stitch two calibrated CCD channels and cubenorm the result.
sun_azimuth_from_top	Get solar azimuth converted to CW-from-top convention.

browse_url

instruments.mro.hirise.browse_url(product_id, annotated=True)

Return the HiRISE EXTRAS browse-JPEG URL for a product ID.

Resolves the EXTRAS path on the U. Arizona HiRISE server. EDR products only have a clean browse; RDR/COLOR products have both clean (.browse.jpg) and annotated (.abrowse.jpg) variants.

[source]

calibrate_channel

instruments.mro.hirise.calibrate_channel(cub, cleanup=True)

Radiometrically calibrate a single HiRISE channel cube.

Runs hical to apply radiometric calibration.

Parameters

Name	Type	Description	Default
cub	Path	Path to a .cub file (output of :func:`ingest_edr`).	required
cleanup	bool	Delete the uncalibrated input cube.	`True`

Returns

Name	Type	Description
	Path	Path to the calibrated cube (`*.cal.cub`).

[source]

create_mosaic

instruments.mro.hirise.create_mosaic(
    obsid,
    color='red',
    ccds=None,
    mapfile=None,
    overwrite=False,
    saveroot=None,
    download=True,
    print_progress=True,
    max_workers=None,
)

Create a HiRISE CCD mosaic from EDR data.

Full processing chain (pymars/HiRISE standard pipeline):

Per channel: download → hi2isis → spiceinit → hical

Per CCD: histitch(balance) → cubenorm → cam2map

Mosaic: equalizer → automos(priority=beneath)

Steps 2-5 are parallelized using process-based parallelism. Intermediate files are deleted after each step to conserve disk.

Parameters

Name	Type	Description	Default
obsid	str	HiRISE observation ID, e.g. `"ESP_013807_2035"`.	required
color	str	CCD color group: `"red"` (default), `"ir"`, or `"bg"`.	`'red'`
ccds	list of int	Specific CCD numbers to include. If None, uses all CCDs for the color (RED: 0-9, IR: 10-11, BG: 12-13). For RED, a common choice is `[4, 5]` for the central nadir pair.	`None`
mapfile	str or Path	ISIS map projection file for `cam2map`. If None, uses ISIS default projection (Sinusoidal).	`None`
overwrite	bool	If True, re-download and reprocess even if the mosaic exists.	`False`
saveroot	Path	Override local storage directory.	`None`
download	bool	If True (default), download EDR files if missing. Set to False if files are already available locally.	`True`
print_progress	bool	If True (default), print step-by-step progress to stdout.	`True`
max_workers	int	Maximum number of parallel workers for steps 2-5. If None, auto-calculates based on available memory (80% of free RAM).	`None`

Returns

Name	Type	Description
	Path	Path to the final mosaic cube.

Examples

>>> create_mosaic("PSP_003092_0985")                     # RED 0-9, full pipeline
>>> create_mosaic("PSP_003092_0985", ccds=[4, 5])        # RED 4+5 central pair
>>> create_mosaic("PSP_003092_0985", color="ir")         # IR mosaic
>>> create_mosaic("PSP_003092_0985", color="bg")         # BG mosaic
>>> create_mosaic("PSP_003092_0985", max_workers=4)      # limit parallelism

[source]

create_mosaics

instruments.mro.hirise.create_mosaics(
    obsid,
    colors=('red',),
    ccds=None,
    mapfile=None,
    overwrite=False,
    **kwargs,
)

Create one HiRISE mosaic per requested color.

A thin orchestration wrapper around :func:create_mosaic. The ccds selection only applies to the RED color group (other colors have only 2 CCDs each, so subsetting isn’t meaningful).

Parameters

Name	Type	Description	Default
obsid	str	HiRISE observation ID.	required
colors	sequence of str	Any subset of `("red", "ir", "bg")`.	`('red',)`
ccds	list of int	CCD numbers to include — applied only to the RED mosaic.	`None`
mapfile	str \| Path \| None	Forwarded to :func:`create_mosaic`.	`None`
overwrite	str \| Path \| None	Forwarded to :func:`create_mosaic`.	`None`
**kwargs	str \| Path \| None	Forwarded to :func:`create_mosaic`.	`None`

Returns

Name	Type	Description
	dict[str, Path]	Mapping color name → mosaic path.

[source]

create_red_mosaic

instruments.mro.hirise.create_red_mosaic(obsid, ccds=(4, 5), **kwargs)

Convenience wrapper for create_mosaic(color='red').

See :func:create_mosaic for full parameter documentation.

[source]

download_edr

instruments.mro.hirise.download_edr(
    obsid,
    colors=None,
    ccds=None,
    saveroot=None,
    overwrite=False,
    max_workers=4,
)

Download HiRISE EDR channel files for an observation.

Downloads in parallel using a thread pool (default 4 workers) with rich progress bars.

Parameters

Name	Type	Description	Default
obsid	str	Observation ID, e.g. `"PSP_003092_0985"`.	required
colors	list of str	Color groups: `"red"`, `"ir"`, `"bg"`. Defaults to `["red"]`.	`None`
ccds	list of int	Limit to specific RED CCD numbers (e.g. `[4, 5]`).	`None`
saveroot	Path	Override storage root.	`None`
overwrite	bool	Re-download even if cached.	`False`
max_workers	int	Number of parallel downloads (default 4).	`4`

Returns

Name	Type	Description
	list of SOURCE_PRODUCT	The downloaded products (with valid `.local_path`).

Raises

Name	Type	Description
	RuntimeError	If any downloads failed.

[source]

edr_products

instruments.mro.hirise.edr_products(
    obsid,
    colors=None,
    ccds=None,
    saveroot=None,
)

Build a list of EDR SOURCE_PRODUCTs for an observation.

Parameters

Name	Type	Description	Default
obsid	str	Observation ID, e.g. `"PSP_003092_0985"`.	required
colors	list of str	Color groups to include: `"red"`, `"ir"`, `"bg"`. Defaults to `["red"]`.	`None`
ccds	list of int	Limit to specific CCD numbers within the selected colors. Only applies to RED (e.g. `[4, 5]` for RED4+RED5).	`None`
saveroot	Path	Override storage root.	`None`

Returns

Name	Type	Description
	list of SOURCE_PRODUCT	Two products per CCD (channels 0 and 1).

[source]

format_meta

instruments.mro.hirise.format_meta(index_key, product_id, *, long=False)

Shape a HiRISE meta row for plp meta / get_meta.

Routes to the EDR or RDR formatter depending on index_key: the two indexes have very different schemas (EDR has channel rows with CCD_NAME/CHANNEL_NUMBER; RDR has merged-color rows with MAP_* / MINIMUM/MAXIMUM_LAT/LON and no CCD columns) and accept different product-id shapes.

Reads the parquet via predicate pushdown + column projection so even a 2.6M-row HiRISE EDR index is interrogated in tens of milliseconds instead of seconds.

[source]

get_browse

instruments.mro.hirise.get_browse(
    product_id,
    annotated=True,
    dest=None,
    force=False,
)

Download a HiRISE browse JPEG and return its local path.

Fetches from the EXTRAS directory at the University of Arizona HiRISE server. Cached locally after first download.

Parameters

Name	Type	Description	Default
product_id	str	HiRISE product ID, e.g. “ESP_013807_2035_RED”, “PSP_003092_0985_COLOR”, or bare observation “ESP_013807_2035” (defaults to RED).	required
annotated	bool	If True (default), fetch the annotated browse (`.abrowse.jpg`) which includes the observation ID and scale bar. If False, fetch the clean browse (`.browse.jpg`).	`True`
dest	Path	Directory to save into. Defaults to planetarypy storage.	`None`
force	bool	Re-download even if cached.	`False`

Returns

Name	Type	Description
	Path	Local path to the browse JPEG.

[source]

get_metadata

instruments.mro.hirise.get_metadata(product_id, index='rdr')

Look up HiRISE metadata from the PDS index.

Parameters

Name	Type	Description	Default
product_id	str	HiRISE product ID (e.g. “ESP_013807_2035_RED”).	required
index	str	Which index to query: “rdr” or “edr”.	`'rdr'`

Returns

Name	Type	Description
	dict	Index row as a dictionary.

[source]

ingest_edr

instruments.mro.hirise.ingest_edr(product)

Convert a HiRISE EDR .IMG to an ISIS cube and initialize SPICE.

Runs hi2isis then spiceinit (web-based kernel fetch).

Parameters

Name	Type	Description	Default
product	SOURCE_PRODUCT	The EDR product to ingest. Must already be downloaded.	required

Returns

Name	Type	Description
	Path	Path to the resulting .cub file.

[source]

map_project

instruments.mro.hirise.map_project(normed, mapfile=None, cleanup=True)

Map-project a calibrated, normalized CCD cube.

Runs cam2map. If no map file is provided, ISIS uses its default Sinusoidal projection.

Parameters

Name	Type	Description	Default
normed	Path	Path to a .cal.norm.cub file.	required
mapfile	str or Path	ISIS map projection file (.map). If None, uses ISIS default.	`None`
cleanup	bool	Delete input cube.	`True`

Returns

Name	Type	Description
	Path	Path to the map-projected cube (`*.cal.norm.map.cub`).

[source]

stitch_channels

instruments.mro.hirise.stitch_channels(
    ch0_cal,
    ch1_cal,
    obsid,
    ccd,
    cleanup=True,
)

Stitch two calibrated CCD channels and cubenorm the result.

Runs histitch with balance=true on channels 0 and 1, then cubenorm to normalize column-to-column variations.

Parameters

Name	Type	Description	Default
ch0_cal	Path	Calibrated .cal.cub files for channels 0 and 1 of the same CCD.	required
ch1_cal	Path	Calibrated .cal.cub files for channels 0 and 1 of the same CCD.	required
obsid	str	Observation ID (for naming the output).	required
ccd	str	CCD identifier, e.g. `"RED4"`.	required
cleanup	bool	Delete input and intermediate files.	`True`

Returns

Name	Type	Description
	Path	Path to the normalized stitched cube (`*.cal.norm.cub`).

[source]

sun_azimuth_from_top

instruments.mro.hirise.sun_azimuth_from_top(product_id, index='rdr')

Get solar azimuth converted to CW-from-top convention.

HiRISE indexes store SUB_SOLAR_AZIMUTH as CW from 3 o’clock. This function converts to CW from image top, suitable for planetarypy.plotting.add_sun_indicator.

Parameters

Name	Type	Description	Default
product_id	str	HiRISE product ID.	required
index	str	Which index: “rdr” or “edr”.	`'rdr'`

Returns

Name	Type	Description
	float	Solar azimuth in degrees, CW from image top.

[source]