Install & Compatibility
Where this runs
tested against v0.24.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 3.577s · 306.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 11.5s · import 3.388s · 302MB
313MB installed
● package 313MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
WCS
✓ from gwcs import WCS
coordinate_frames
✓ from gwcs import coordinate_frames as cf
models
✓ from astropy.modeling import models
Transforms are Astropy models, not directly from gwcs.
units
✓ from astropy import units as u
coordinates
✓ from astropy import coordinates as coord
This example demonstrates how to construct a simple imaging GWCS object by chaining Astropy models and defining coordinate frames. It transforms input pixel coordinates to ICRS sky coordinates, illustrating the core pipeline concept of GWCS.
import numpy as np
from astropy.modeling import models
from astropy import units as u
from astropy import coordinates as coord
from gwcs import wcs
from gwcs import coordinate_frames as cf
# Define the transformations
pixel_scale = 0.05 * u.arcsec / u.pixel
detector_center_pixel = (500, 500)
reference_sky_coord = coord.SkyCoord(ra=20 * u.deg, dec=30 * u.deg, frame='icrs')
# 1. Shift pixel coordinates to have (0,0) at detector center
pixel_to_intermediate_frame = models.Shift(-detector_center_pixel[0] * u.pixel) & \
models.Shift(-detector_center_pixel[1] * u.pixel)
# 2. Apply pixel scale
intermediate_to_celestial_angles = models.Scale(pixel_scale) & models.Scale(pixel_scale)
# 3. Tangent projection (TAN) from celestial angles to sky coordinates
celestial_angles_to_sky = models.Pix2Sky_TAN()
# 4. Rotate and shift to final celestial position (simple case for illustration)
# In a real scenario, this would be more complex, involving proper rotation models
# and matching reference points. Here we directly set the reference_sky_coord.
# Define the frames
detector_frame = cf.Frame2D(name="detector", axes_names=('x', 'y'), unit=(u.pixel, u.pixel))
celestial_frame = cf.CelestialFrame(reference_frame=reference_sky_coord.frame,
name='icrs', unit=(u.deg, u.deg))
# Build the GWCS pipeline
pipeline = [
wcs.Step(detector_frame, pixel_to_intermediate_frame | intermediate_to_celestial_angles | celestial_angles_to_sky),
wcs.Step(celestial_frame, None)
]
# Create the WCS object
image_wcs = wcs.WCS(pipeline)
# Example transformation
pixel_coords = np.array([[100, 200], [500, 500]]) * u.pixel
world_coords = image_wcs.pixel_to_world(pixel_coords[:, 0], pixel_coords[:, 1])
print(f"Input pixel coordinates:\n{pixel_coords}")
print(f"Output world coordinates:\n{world_coords}")
Errors
Common errors & fixes
ValueError: operands could not be broadcast together with shapes (N,) (1,N)
In versions prior to 0.25.0, 'vector' shaped arrays (e.g., `(N,)` instead of `(1, N)`) would lose all but their first entry if `with_units=True` was used in `LabelMapperArray`.
fixUpgrade to `gwcs` version 0.25.0 or later. Ensure array inputs have the expected shape (e.g., `(1, N)` for 1D data or `(N, M)` for 2D data) if `with_units` (though deprecated) is implicitly used or affects behavior.
TypeError: 'NoneType' object is not callable
Prior to version 1.0.1, GWCS evaluation could fail when input or output frames were `None` or `EmptyFrame` objects, leading to incorrect or uncallable transform steps.
fixUpgrade to `gwcs` version 1.0.1 or later. Ensure that coordinate frames are properly defined and not `None` or `EmptyFrame` where a valid frame is expected.
ValueError: Cannot insert a transform before the first frame in the pipeline.
Attempting to insert a new transform before the initial coordinate frame in a `GWCS` pipeline (e.g., using `wcs.insert_transform(frame, transform, before=True)` with the `input_frame`). This was explicitly disallowed or raised an error from version 1.0.0 onwards.
fixTransforms should typically be inserted between existing frames or appended. If modifying the very beginning of the pipeline, reconstruct the `WCS` object with the desired initial transform and frame, or append/insert after the initial frame.
Upgrade
Version history
1.0.3latest on PyPI · released Feb 12, 2026
Audit
Dependencies
astropyrequiredCore functionality relies heavily on astropy.modeling for transforms, astropy.units for quantities, and astropy.coordinates for celestial frames.
asdfoptionalRecommended for saving and loading GWCS objects.
pythonrequiredRequires Python 3.11 or later.