pyavm

0.9.9 · active · verified Fri Apr 17

pyavm is a pure-Python library for reading and writing AVM (Astronomical Visualization Metadata) information to/from FITS and JPEG files. It leverages Astropy for FITS handling and Pillow for JPEG. The current version is 0.9.9, and it's actively maintained as part of the Astropy ecosystem, with regular but pre-1.0.0 releases.

Common errors

```
ModuleNotFoundError: No module named 'astropy.io.fits'
```
cause `astropy` (or specifically `astropy.io.fits`) is not installed or the installed version is incompatible with `pyavm`.

fix Install `astropy` using `pip install astropy` or, preferably, `pip install pyavm[astropy,pil]` to include all core dependencies.
```
FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_image.jpg'
```
cause The image file path provided to `AVM.from_image()` or `AVM.add_spatial_to_image()` does not exist on disk.

fix Verify that the image file is present at the specified path before attempting to read or write AVM metadata.
```
ImportError: cannot import name 'AVM' from 'pyavm'
```
cause Incorrect import statement or `pyavm` is not installed, or an outdated version of `pyavm` is installed where the `AVM` class might have been located differently.

fix Ensure `pyavm` is installed and up-to-date with `pip install --upgrade pyavm`. The correct import is `from pyavm import AVM`.

Warnings

gotcha pyavm requires an existing image file on disk to embed or extract AVM metadata. It does not create or modify image data (pixel arrays) directly, only the metadata within the file.
Fix: Ensure the image file (JPEG or FITS) exists at the specified path before calling `AVM.from_image()` or `AVM.add_spatial_to_image()`.
breaking As a pre-1.0.0 library, the API for pyavm can undergo changes even in minor versions (e.g., from 0.8.x to 0.9.x). While core functionality remains relatively stable, new features or less frequently used methods might be refactored.
Fix: Always consult the changelog in the official documentation or GitHub repository for each new release to identify any API adjustments or breaking changes.
gotcha pyavm relies on specific external libraries for file handling: `Pillow` for JPEG images and `astropy` for FITS files. If these are not installed, or their versions are incompatible, operations on those file types will fail.
Fix: It is recommended to install `pyavm` with its optional dependencies using `pip install pyavm[astropy,pil]` to ensure all necessary components are present.

Install

pip install pyavm Base install
pip install pyavm[astropy,pil] Install with all core dependencies (recommended)

Imports

AVM
```
from pyavm import AVM
```

Quickstart

This quickstart demonstrates how to create an AVM object, populate it with metadata, embed this metadata into an existing JPEG image, and then read the AVM data back from the modified image. It uses Pillow to create a dummy image as a prerequisite.

from pyavm import AVM
from PIL import Image
import numpy as np
import os

# --- Create a dummy image for demonstration ---
img_data = np.zeros((200, 300, 3), dtype=np.uint8)
dummy_path = "dummy_image.jpg"
Image.fromarray(img_data).save(dummy_path)

# --- Example: Create and add AVM metadata to an image ---
avm = AVM()
avm.Creator = "John Doe"
avm.Subject = "Test Astronomical Image"
avm.Date = "2024-04-17T12:00:00"
avm.Spatial_Scale = 1.25 # arcsec/pixel

output_path = "image_with_avm.jpg"
# Add spatial AVM metadata from the AVM object to the image
avm.add_spatial_to_image(dummy_path, output_path)

print(f"AVM metadata added to '{output_path}'")

# --- Example: Read AVM metadata from an existing image ---
avm_read = AVM.from_image(output_path)

print(f"\nMetadata read from '{output_path}':")
print(f"  Creator: {avm_read.Creator}")
print(f"  Spatial Scale: {avm_read.Spatial_Scale}")

# --- Clean up generated files ---
os.remove(dummy_path)
os.remove(output_path)

view raw JSON →