Python API

Introduction

In order to avoid generating useless files when working with data already in memory, a Python interface is published. The package comes with a library, public interface of which is contained in module api. For example, assuming the photometric channels are NumPy arrays i, y, j h, the RGB (or, rather, BGR image) is rendered as:

import numpy as np
import azulero.api as azul

iyjh = np.stack([i, y, j, h])
bgr = azul.process_iyjh(iyjh)

Image layout

Grayscale image axes are:

  1. Y-axis from bottom to top,

  2. X-axis from left to right.

In addition, color images have a third axis:

  1. color axis ordered as Blue, Green, Red.

For convenience, azul retrieve features have also been ported to the API, as class DataProvider (argument data="labs" triggers Datalabs retrieval mode, see azul retrieve):

from astropy.coordinates import Angle, SkyCoord
from pathlib import Path
import azulero.api as azul

coord = SkyCoord.from_name("NGC6505")
radius = Angle("30s")
dsr = "Q1_R1"

provider = azul.DataProvider("PDR", data="labs")
tiles = provider.query_coord_tiles(coord, [dsr], ["WIDE"])
datafiles = provider.query_tile_datafiles(tiles[0], dsr)
provider.download_cutouts(datafiles, Path("workdir"), coord, radius)

API reference

class azulero.api.DataProvider(
name: str,
user: str | None = None,
data_store: str | None = None,
tiling_file: Path | None = None,
)

Data provider.

Parameters:

  • name – The data provider name.

  • user – The data provider user name (optional if the netrc file was set up).

  • data_store – The data store name (use "labs" in ESA Datalabs).

  • tiling_file – The tiling Geojson file, for optimization purpose.

download_cutouts(
datafiles: list[str],
workdir: Path,
center: SkyCoord,
radius: Angle,
overwrite: bool = False,
) → list[Path]

Download tile cutouts.

Parameters:

  • datafiles – The list of datafile names.

  • workdir – The destination directory (will be created if missing).

  • center – The cutout center.

  • radius – The cutout radius.

  • overwrite – Boolean flag to enable or disable overwriting.

Returns:

The resulting list of cutout paths.

download_datafiles(
datafiles: list[str],
workdir: Path,
overwrite: bool = False,
) → list[Path]

Download and decompress datafiles of an entire tile.

Parameters:

  • datafiles – The list of datafile names.

  • workdir – The destination directory.

  • overwrite – Boolean flag to enable or disable overwriting.

Returns:

The resulting list of datafile paths.

query_coord_tiles(
coord: SkyCoord,
dsrs: list[str],
modes: list[str],
) → list[str]

Query the list of tiles which contain a given coordinate.

Parameters:

  • coord – The target coordinate.

  • dsrs – The ordered list of dataset releases.

  • modes – The ordered list of processing modes.

Returns:

The list of tile indices.

query_tile_datafiles(
index: str,
dsr: str,
) → list[str]

Query the datafiles of a tile.

Parameters:

  • index – The tile index.

  • dsr – The Dataset Release name.

Returns:

The list of file names.

class azulero.api.Transform(
inpaint_edges: bool = False,
inpaint_area: int = -1,
iyjh_zero_points: tuple = (24.5, 29.8, 30.1, 30.0),
iyjh_scaling: tuple = (2.2, 1.3, 1.2, 1.0),
iyjh_fwhm: tuple = (1.6, 3.5, 3.4, 3.5),
sharpen_strength: float = 0.5,
nir_to_l: float = 0.2,
i_to_b: float = 1.0,
y_to_g: float = 0.5,
j_to_r: float = 0.25,
hue: float = -20.0,
saturation: float = 1.2,
stretch: float = 27.5,
bw: tuple = (28.5, 22.5),
neg_overshoot: float = 0.4,
bgr_curves: tuple = ([(0.5, 0.55)], [], []),
)

Transformation parameters.

Parameters:

  • inpaint_edges – Enable edge inpainting.

  • inpaint_area – Upper limit on the inpainting region areas.

  • iyjh_zero_points – Zero points of each channel.

  • iyjh_scaling – Scaling of each channel (for white balance).

  • iyjh_fwhm – PSF full width at half-maximum of each channel.

  • sharpen_strength – Unsharp masking strength.

  • nir_to_l – NIR-to-L rate.

  • i_to_b – I-to-B rate.

  • y_to_g – Y-to-G rate.

  • j_to_r – J-to-R rate.

  • hue – Hue rotation angle in degrees.

  • saturation – Saturation gain.

  • stretch – Stretching parameter.

  • neg_overshoot – Negative overshooting parameter.

  • bw – Black and white points in AB-mag.

  • bgr_curves – Curve adjustment knots for each channel.

azulero.api.process_iyjh(
iyjh: ndarray,
wcs: WCS | None = None,
transform: Transform = Transform(),
output: str = '',
) → ndarray

Process an image according to transformation parameters, optionally save the rendered color image.

Parameters:

  • iyjh – A stack of the I, Y, J, H arrays (e.g. iyjh[1] is the NIR-Y channel).

  • wcs – The WCS parameters or None.

  • transform – The transformation parameters.

  • output – The output file name. An empty string disables writing.

Returns:

A normalized BGR image.

azulero.api.read_iyjh(
path: Path,
slicing: tuple[slice, slice] | None = None,
channels: list[str] = ['VIS', 'NIR-Y', 'NIR-J', 'NIR-H'],
template: str = '*{channel}*.fits',
)

Read the I, Y, J, H channels from a directory containing single-image FITS (SIF) files, or from a single multi-extension FITS (MEF) file. In the former case, if more than one SIF file is found for a channel, they will be median-stacked.

Parameters:

  • path – The path to the directory or FITS file.

  • slicing – An optional slicing for loading only a region in memory.

  • channels – The channel names. For a MEF file, the extension names must match the channel names.

  • template – The glob pattern template in which {channel} will be substituted by the channel names, in order to locate the SIF files.

Returns:

The I, Y, J, H stack.