Metadata-Version: 2.5
Name: ftir-OMNIC-map-reader
Version: 1.1.0
Summary: Load Thermo OMNIC .map FTIR files into Python as xarray datasets
Project-URL: Documentation, https://ftir-omnic-map-reader.readthedocs.io/
Project-URL: Source, https://github.com/whtowbin/FTIR_OMNIC_MAP_Reader
Project-URL: Issues, https://github.com/whtowbin/FTIR_OMNIC_MAP_Reader/issues
Project-URL: Changelog, https://github.com/whtowbin/FTIR_OMNIC_MAP_Reader/blob/main/CHANGELOG.md
Author-email: Henry Towbin <24940778+whtowbin@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE.txt
License-File: NOTICE
Keywords: FTIR,Hyperspectral,OMNIC,Thermo,spectroscopy,xarray
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.10.1
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2
Requires-Dist: pillow>=10
Requires-Dist: xarray>=2024.6
Requires-Dist: zarr>=2.18
Provides-Extra: netcdf
Requires-Dist: h5netcdf>=1.3; extra == 'netcdf'
Requires-Dist: h5py>=3.8; extra == 'netcdf'
Provides-Extra: parquet
Requires-Dist: pyarrow>=14; extra == 'parquet'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6; extra == 'yaml'
Provides-Extra: zarr
Description-Content-Type: text/markdown

# FTIR OMNIC Map Reader

Read Thermo OMNIC `.map` files (FTIR maps, line scans and point lists) into Python as NumPy arrays or xarray datasets.
It returns the spectra, the spectral axis, the stage position of every spectrum, the background spectra, the video or
mosaic images with their stage coordinates, and the collection metadata that could be decoded.

Documentation: <https://ftir-omnic-map-reader.readthedocs.io/>

## Install

```console
pip install ftir-OMNIC-map-reader
pip install "ftir-OMNIC-map-reader[yaml,parquet,netcdf]"   # optional: YAML metadata, Parquet points, netCDF export
```

With [uv](https://docs.astral.sh/uv/): `uv add ftir-OMNIC-map-reader`. Python 3.10 or newer.

## Quick start

```python
from ftir_map import read_omnic

m = read_omnic("my_map.map")
m.map_kind  # "grid", "line", "points" or "array"
m.spectra.shape  # (n_points, n_axis), in file order; NaN is kept as stored
m.axis  # wavenumbers in cm-1 (m.axis_unit == "cm-1")
m.x, m.y  # stage position of each spectrum in um
ds = m.to_xarray()  # spectra on (y, x, wavenumber) for a grid, (point, wavenumber) otherwise
```

`read_omnic` raises `OmnicFormatError` (a `ValueError`) for a file that is not an OMNIC map or holds no spectra.

## Map kinds

| `map_kind` | What it is | xarray layout of `spectra` |
|---|---|---|
| `grid` | rectangular area map | (y, x, wavenumber) |
| `array` | array-detector map; its pixels fill a grid | (y, x, wavenumber) |
| `line` | profile along a line | (point, wavenumber) |
| `points` | point-to-point map or irregular positions | (point, wavenumber) |

Interferogram maps (`m.data_kind == "interferogram"`) have `axis_unit == "points"`, and the last dimension is named
`axis`. `m.wavenumber` is the same as `m.axis` for spectra and raises an error for interferograms.

## Exports

Each export is described, with example output, in [docs/site/exports.md](docs/site/exports.md).

```python
ds = m.to_xarray()  # xarray.Dataset, attrs hold the metadata
spectra, axes, positions, metadata = m.to_numpy()  # arrays and plain dicts
everything = m.to_dict()  # spectra, axes, positions, titles, times, backgrounds, images
m.to_zarr("my_map.zarr")  # refuses to overwrite by default
images = m.to_images()  # video images or mosaic tiles with stage extents
```

### Writing files

```python
m.save_metadata("meta.json")  # or .yaml, .csv
m.save_points("points.csv")  # one row per spectrum: x, y, z, row, column, title, time, background
m.save_spectra("spectra.npz")  # or .csv, .zarr; .nc is opt-in ([netcdf] extra)
m.save_images("images/", format="png")  # PNG or TIFF or the original files, plus world files and an index
m.export_all("my_map_export/")  # all of the above in one folder with a README.txt
```

The same from the command line:

```console
ftir-map info my_map.map
ftir-map export my_map.map --out my_map_export --spectra npz --metadata yaml --images tiff
```

Showing a video image with the map positions:

```python
import matplotlib.pyplot as plt

for image in m.to_images():
    plt.imshow(image.array, extent=image.extent)  # extent = (xmin, xmax, ymin, ymax) in um; no flip needed
plt.plot(m.x, m.y, "r.")
```

## Unpack maps into an open project folder

`ftir-map unpack` turns proprietary `.map` files into a folder of open files: spectra in Zarr (`spectra.zarr`, readable with
`xarray.open_zarr` or `zarr.open` in Python, and with the Zarr packages of R and Julia; use `--spectra csv` for MATLAB
or Excel), `points.csv`, `map.json` with all metadata, and the embedded images with
world files. Give it files and/or folders; it finds `.map` files recursively, lists unreadable ones in the catalog, and
skips maps that are already unpacked. The format is in [docs/site/unpacked_format.md](docs/site/unpacked_format.md).

```console
ftir-map unpack "Bristol 2017/" other_map.map --out my_project [--spectra zarr|csv|nc] [--png] [--copy-source]
# --spectra nc is an opt-in export and needs the [netcdf] extra
ftir-map catalog my_project
```

```python
import ftir_map

project = ftir_map.unpack(["Bristol 2017/"], "my_project")  # or ftir_map.open_project("my_project")
project.catalog  # pandas DataFrame, one row per source file
m = project.load(project.names[0])  # an OmnicMap, rebuilt from the open files
ds = project.to_xarray(project.names[0])
ftir_map.load("my_project/maps/my_map")  # also reads one unpacked map, a project, or a .map file
```

## Metadata

`m.collection` (number of points, first and last X, scans, laser frequency, mirror velocity and more),
`m.map_definition` (kind, ranges, step, title, original file name), `m.title`, `m.file_time`, `m.history`, the
per-spectrum `m.titles`, `m.times_s` and `m.background_index`, and `m.backgrounds` (spectrum, title and time of each
background). `m.block_bytes(key)` returns the raw bytes of any block this reader does not decode. The same metadata,
as JSON-serializable values, is in `ds.attrs` and in the last item of `to_numpy()`. Which fields are verified against
OMNIC's own exports, and which are inferred, is in [docs/site/file_format.md](docs/site/file_format.md).

## Older interface

`Load_Omnic_Map` from version 1.0 still works and returns the same output for grid maps. It also reads line scans and
point maps now. A file it cannot read gives a warning and `None`.

```python
from ftir_map.LoadOmnicMAP import Load_Omnic_Map

ds = Load_Omnic_Map("my_map.map")  # xarray.Dataset on (y, x, wn)
d = Load_Omnic_Map("my_map.map", format="Dictionary")  # keys data, x, y, wn, metadata
```

It replaces NaN by 0, as PyMca did; `read_omnic` does not. The PyMca-derived modules `PyMca_OmnicMap`,
`PyMca_Array_OmnicMap` and `LoadOmnicArrayMAP` are deprecated and will be removed in 2.0.

## Credits and license

The format knowledge behind the first versions comes from the OMNIC reader in
[PyMca](https://github.com/vasole/pymca) (V.A. Sole, European Synchrotron Radiation Facility, MIT license). See
[NOTICE](NOTICE). The rest of the format was worked out by comparing 81 files with OMNIC's own exports. MIT license,
see [LICENSE.txt](LICENSE.txt). Changes are listed in [CHANGELOG.md](CHANGELOG.md); release steps in
[docs/RELEASING.md](docs/RELEASING.md).
