Registry / data / gwcs
library1.0.3pypypi✓ verified 84d ago

GWCS (Generalized World Coordinate System) is an Astropy affiliated package designed for managing the World Coordinate System of astronomical data. It provides a flexible and general approach to defining and transforming coordinates between detector pixels and various world coordinate systems. Tightly integrated with Astropy, it leverages Astropy's modeling, units, and coordinates frameworks to build complex transformation pipelines. The library maintains an active development pace with frequent patch and minor releases.

pip install gwcs
INSTALL
IMPORT
SIG · GWCS
G
gwcs
datapythonv1.0.3
Install
11.5s avg
Import
3482ms
Disk
313MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 3.577s · 306.4MB
glibc
py 3.103.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}")
Debug
Known issues
breakingAs of GWCS 0.25.0, support for Python 3.10 has been dropped. Users must upgrade to Python 3.11 or later to use recent versions of `gwcs`.
fix
Upgrade your Python environment to 3.11 or newer: `conda install python=3.11` or `pyenv install 3.11`.
affects: >=0.25.0
deprecatedThe `with_units` argument (e.g., in `LabelMapperArray`) was deprecated in version 0.26.0 and will be removed in future releases. It caused issues with array-like inputs losing entries.
fix
Avoid using `with_units=True`. Ensure transforms are defined to handle units directly. If encountering data loss with array inputs, upgrade `gwcs` to 0.25.0+ and review your transform definitions to ensure unit-aware operations.
affects: >=0.26.0
deprecatedThe private `_toindex` function was deprecated in 0.26.1 in favor of the public `to_index` function.
fix
Replace calls to `_toindex` with `to_index`.
affects: >=0.26.1
gotchaGWCS and Astropy have different default conventions for ordering multi-dimensional bounding boxes ('F' (x, y) for GWCS vs. 'C' (y, x) for Astropy). Setting `bounding_box` directly on a GWCS object will convert to GWCS's 'F' ordering and issue a `GwcsBoundingBoxWarning` if a conversion occurs.
fix
Be mindful of the coordinate order. It is recommended to set the bounding box directly on the GWCS object and heed the warning, or use `bind_bounding_box` with the `order` argument if setting on the transform directly.
affects: All versions
gotchaThe `WCS.numerical_inverse()` method may raise `NoConvergence` exceptions if the iterative process fails to converge or diverges. This can lead to `NaN` or `Inf` values in results if not handled.
fix
Handle `NoConvergence` exceptions explicitly, or set `quiet=True` and `detect_divergence=True` with `adaptive=True` in `numerical_inverse()` to manage non-converging points. Inspect the `divergent` or `slow_conv` attributes of the exception for problematic indices.
affects: All versions
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`.
fix
Upgrade 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.
fix
Upgrade 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.
fix
Transforms 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.
Agent activity
6 hits · last 30 days
node
6
Resources