![Logo](https://raw.githubusercontent.com/kabasset/azulero/v0.1.0/azul.png)

# Bring colors to Euclid tiles!

Azul(ero)* is a toolbox which, among others, provides scripts to download and merge VIS and NIR observations over a MER tile.
For rendering color images, `azul process` detects and inpaints bad pixels (cold pixels, saturated stars...),
and combines the 4 channels (I, Y, J, H) into an sRGB image.
Input data files can be selected with `azul find` and then downloaded with `azul retrieve`,
which connects to public (SAS) or private (EAS) data archives.
Last but not least, `azul roam` produces flowing videos by panning and zooming images.

*I started this project when Euclid EROs came out...

# License

[Apache-2.0](https://raw.githubusercontent.com/kabasset/azulero/refs/tags/v0.1.0/LICENSE)

# Disclaimer

⚠️ **This is a beta version!** ⚠️

* The tool is far from perfect and can be frustrating.
* Error cases are not handled and messages may be cryptic or misleading.
* Please make sure to read the "How to help?" section below before using this version.
* If something is not documented, it does not exist!

# Installation and setup

Install the `azulero` package with:

```
pip install azulero
```

If you wish to access Euclid-internal data with `azul retrieve`, setup the `~/.netrc` file (or `_netrc` on Windows) for `eas-dps-rest-ops.esac.esa.int` and `euclidsoc.esac.esa.int` with your Euclid credentials:

```xml
machine eas-dps-rest-ops.esac.esa.int
  login <login>
  password <password>
machine euclidsoc.esac.esa.int
  login <login>
  password <password>
```

For `azul find`, download the geojson file which monitors MER processing, e.g., for DR1:
https://gitlab.euclid-sgs.uk/sy-tools/ST_SMT_DATA/-/raw/DR1/data/DpdMerFinalCatalog.geojson?ref_type=heads

# Basic usage

The typical workflow is as follows:

* 🎯 Find the tile indices of your objects or coordinates with `azul find`.
* 📥 Download the MER-processed FITS file of your tiles with `azul retrieve`.
* ✂️ Optionally select the region to be processed with `azul crop`.
* 🌟 Blend the channels and inpaint artifacts with `azul process`.
* 🎬 Generate a video from the image with `azul roam`.

Usage:

```xml
azul [--workspace <workspace>] find [<objects>] [--radec <coordinates>]
azul [--workspace <workspace>] retrieve [--from <provider>] <tile_indices>
azul [--workspace <workspace>] crop <tile_index>
azul [--workspace <workspace>] process <tile_slicing>
azul [--workspace <workspace>] roam <image> <sequence>
```

with:

* `<workspace>` - The parent directory to save everything, in which one folder per tile will be created (defaults to the current directory).
* `<object>` - A space-separated list of object names, e.g. `M82 NGC6536`.
* `<coordinates>` - RA/dec coordinates in decimal degrees, e.g. `266.9397155 +64.0472200`; Option `--radec` can be specified multiple times.
* `<provider>` - The data archive name, e.g. `sas` for public releases.
* `<tile_indices>` - The space-separated list of tiles to be downloaded, typically the result of `azul find`.
* `<tile_index>` - A single tile index.
* `<tile_slicing>` - A single tile index, optionally followed by a slicing à-la NumPy, typically the result of `azul crop`.
* `<image>` - The path to an input image (not necessarily produced by Azul).
* `<sequence>` - The roaming configuration file: see the [format description](roam.md) for details.

# Example

Here is an example output and the commands which produced it below:

![adjusted](https://raw.githubusercontent.com/kabasset/azulero/develop/102159776_adjusted.jpg)

> Credit: ESA Euclid/Euclid Consortium/NASA/Q1-2025/Antoine Basset (CNES)

```
azul find 271.1026785 +66.9128392
azul retrieve 102159776 --from sas
azul crop 102159776
azul process 102159776[6000:7000,5000:7000] --yg 0.75 --jr 0.9 -w 22.5
```
I have post-processed the output to my liking:

![post](https://raw.githubusercontent.com/kabasset/azulero/develop/102159776_post.jpg)

> Credit: ESA Euclid/Euclid Consortium/NASA/Q1-2025/Antoine Basset (CNES)

> The two thick blue rings 💍 are artifacts of the VIS instrument known as ghosts.
> To my knowledge, the galaxy in the center has never been resolved this way.
> Rendering the image allowed me to discover this is a splendid polar-ring 💍 galaxy!
> The previously unseen golden structure top left may be an Einstein ring 💍, possibly with two deflectors -- the question remains open. 

As you can see, getting a nice image required a bit of parametrization.
This is because we are using the public Q1 data, and there were prominent artifacts right in the middle of the Einstein ring.
DR1 data, to be published in 2026, have a much better signal-to-noise ratio, less artifacts, and default parameters give very good results.
I already rendered the DR1 version of this field; I cannot share it today, but I can already tell you it is mesmerizing 😏

From the same tile, here is an example over a region with less artifacts, processed with default parameters:

![UGC11116](https://raw.githubusercontent.com/kabasset/azulero/develop/UGC11116.jpg)

> Credit: ESA Euclid/Euclid Consortium/NASA/Q1-2025/Antoine Basset (CNES)

> [UGC 11116](https://simbad.u-strasbg.fr/simbad/sim-id?Ident=Z%20322-30)

```
azul process 102159776[11000:12000,7500:9500]
```

It is now possible to generate pan-and-zoom videos with `azul roam`, like [this](https://www.youtube.com/watch?v=mgWAo0JwlqM).
Check the [dedicated documentation](roam.md) for more details.

# Advanced usage

One day I'll find some time to write something useful here... 🤔

In the meantime, please read [the algorithm description](algo.md) and check help messages:

```
azul -h
azul find -h
azul retrieve -h
azul crop -h
azul process -h
azul roam -h
```

# How to help?

* [Report bugs, request features](https://github.com/kabasset/azulero/issues), tell me what you think of the tool and results...
* Mention myself (Antoine Basset, CNES) and/or [`azulero`](https://pypi.org/project/azulero/)
  when you publish images processed with this tool (see example credits above).
* Share with me your images, I'm curious!

# Contributors

* Mischa Schirmer (MPIA): Azul's color blending is freely inspired by that of Mischa's script `eummy.py`.
* Téo Bouvard (Thales): Drafed `retrieve`.
* Rollin Gimenez (CNES): Fixed packaging.
* Kane Nguyen-Kim (IAP): Provided URLs for retrieving public data.
* Gian Paolo Candini (CSIC): Investigated rendering issues and improved parametrization.

# Acknowledgements

* 🔥 Congratulations to the whole Euclid community; The mosaics are simply unbelievable!
* 😍 Thank you also for answering my dummy questions on the contents of the images I posted.
