World Coordinate Systems

WCS classes

class jax_galsim.BaseWCS

Bases: BaseWCS

The base class for all other kinds of WCS transformations.

LAX-backend implementation of galsim.wcs.BaseWCS().

Original GalSim Documentation

All the functions the user will typically need are defined here. Most subclasses just define helper functions to implement each particular WCS definition. So this base class defines the common interface for all WCS classes.

There are several types of WCS classes that we implement. The basic class hierarchy is:

`BaseWCS`
    --- `EuclideanWCS`
            --- `UniformWCS`
                    --- `LocalWCS`
    --- `CelestialWCS`

These base classes are not constructible. They do not have __init__ defined.

1. LocalWCS classes are those which really just define a pixel size and shape. They implicitly have the origin in image coordinates correspond to the origin in world coordinates. They are primarily designed to handle local transformations at the location of a single galaxy, where it should usually be a good approximation to consider the pixel shape to be constant over the size of the galaxy.

   Currently we define the following LocalWCS classes:

   - `PixelScale`
   - `ShearWCS`
   - `JacobianWCS`
   

2. UniformWCS classes have a constant pixel size and shape, but they have an arbitrary origin in both image coordinates and world coordinates. A LocalWCS class can be turned into a non-local UniformWCS class when an image has its bounds changed, e.g. by the commands Image.setCenter, Image.setOrigin or Image.shift.

   Currently we define the following non-local, UniformWCS classes:

   - `OffsetWCS`
   - `OffsetShearWCS`
   - `AffineTransform`
   

3. EuclideanWCS classes use a regular Euclidean coordinate system for the world coordinates, using PositionD for the world positions. We use the notation (u,v) for the world coordinates and (x,y) for the image coordinates.

   Currently we define the following non-uniform, EuclideanWCS class:

   - `UVFunction`
   

4. CelestialWCS classes are defined with their world coordinates on the celestial sphere in terms of right ascension (RA) and declination (Dec). The pixel size and shape are always variable. We use CelestialCoord for the world coordinates, which helps facilitate the spherical trigonometry that is sometimes required.

   Currently we define the following CelestialWCS classes: (All but the first are defined in the file fitswcs.py.)

   • RaDecFunction

   • AstropyWCS – requires astropy.wcs python module to be installed

   • PyAstWCS – requires starlink.Ast python module to be installed

   • WcsToolsWCS – requires wcstools command line functions to be installed

   • GSFitsWCS – native code, but has less functionality than the above

There are also a few factory functions in fitswcs.py intended to act like class initializers:

• FitsWCS tries to read a fits file using one of the above classes and returns an instance of whichever one it found was successful. It should always be successful, since its final attempt uses AffineTransform, which has reasonable defaults when the WCS key words are not in the file, but of course this will only be a very rough approximation of the true WCS.

• TanWCS constructs a simple tangent plane projection WCS directly from the projection parameters instead of from a fits header.

• FittedSIPWCS constructs a TAN-SIP WCS by fitting to a list of reference celestial and image coordinates.

Some things you can do with a WCS instance:

• Convert positions between image coordinates and world coordinates (sometimes referred to as sky coordinates):

  >>> world_pos = wcs.toWorld(image_pos)
  >>> image_pos = wcs.toImage(world_pos)
  

  Note: the transformation from world to image coordinates is not guaranteed to be implemented. If it is not implemented for a particular WCS class, a NotImplementedError will be raised.

  The image_pos parameter should be a PositionD. However, world_pos will be a CelestialCoord if the transformation is in terms of celestial coordinates (if wcs.isCelestial() == True). Otherwise, it will be a PositionD as well.

• Convert a GSObject that is defined in world coordinates to the equivalent profile defined in terms of image coordinates (or vice versa):

  >>> image_profile = wcs.toImage(world_profile)
  >>> world_profile = wcs.toWorld(image_profile)
  

  For non-uniform WCS types (for which wcs.isUniform() == False), these need either an image_pos or world_pos parameter to say where this conversion should happen:

  >>> image_profile = wcs.toImage(world_profile, image_pos=image_pos)
  

• Construct a local linear approximation of a WCS at a given location:

  >>> local_wcs = wcs.local(image_pos = image_pos)
  >>> local_wcs = wcs.local(world_pos = world_pos)
  

  If wcs.toWorld(image_pos) is not implemented for a particular WCS class, then a NotImplementedError will be raised if you pass in a world_pos argument.

  The returned local_wcs is usually a JacobianWCS instance, but see the doc string for local for more details.

• Construct a full affine approximation of a WCS at a given location:

  >>> affine_wcs = wcs.affine(image_pos = image_pos)
  >>> affine_wcs = wcs.affine(world_pos = world_pos)
  

  This preserves the transformation near the location of image_pos, but it is linear, so the transformed values may not agree as you get farther from the given point.

  The returned affine_wcs is always an AffineTransform instance.

• Get some properties of the pixel size and shape:

  >>> area = local_wcs.pixelArea()
  >>> min_linear_scale = local_wcs.minLinearScale()
  >>> max_linear_scale = local_wcs.maxLinearScale()
  >>> jac = local_wcs.jacobian()
  >>> # Use jac.dudx, jac.dudy, jac.dvdx, jac.dvdy
  

  Non-uniform WCS types also have these functions, but for them, you must supply either image_pos or world_pos. So the following are equivalent:

  >>> area = wcs.pixelArea(image_pos)
  >>> area = wcs.local(image_pos).pixelArea()
  

• Query some overall attributes of the WCS transformation:

  >>> wcs.isLocal()       # is this a local WCS?
  >>> wcs.isUniform()     # does this WCS have a uniform pixel size/shape?
  >>> wcs.isCelestial()   # are the world coordinates on the celestial sphere?
  >>> wcs.isPixelScale()  # is this either a PixelScale or an OffsetWCS?
  

toWorld(*args, **kwargs)

Convert from image coordinates to world coordinates.

LAX-backend implementation of galsim.wcs.toWorld().

Original GalSim Documentation

There are essentially four overloaded versions of this function here.

1. The first converts a Position from image coordinates to world coordinates. It returns the corresponding position in world coordinates as a PositionD if the WCS is a EuclideanWCS, or a CelestialCoord if it is a CelestialWCS:

   >>> world_pos = wcs.toWorld(image_pos)
   

   Equivalent to posToWorld.

2. The second is nearly the same, but takes x and y values directly and returns either u, v or ra, dec, depending on the kind of wcs being used. For this version, x and y may be numpy arrays, in which case the returned values are also numpy arrays:

   >>> u, v = wcs.toWorld(x, y)                 # For EuclideanWCS types
   >>> ra, dec = wcs.toWorld(x, y, units=units) # For CelestialWCS types
   

   Equivalent to xyTouv or xyToradec.

3. The third converts a surface brightness profile (a GSObject) from image coordinates to world coordinates, returning the profile in world coordinates as a new GSObject. For non-uniform WCS transforms, you must provide either image_pos or world_pos to say where the profile is located, so the right transformation can be performed. And optionally, you may provide a flux scaling to be performed at the same time:

   >>> world_profile = wcs.toWorld(image_profile, image_pos=None, world_pos=None,
                                   flux_ratio=1, offset=(0,0))
   

   Equivalent to profileToWorld.

4. The fourth converts a shear measurement (a Shear) from image coordinates to world coordinates. As above, for non-uniform WCS transforms, you must provide either image_pos or world_pos. If the wcs is a CelestialWCS, then the returned shear follows the convention used by TreeCorr (among others) for shear on a sphere, namely in the local coordinates where north is up and west is to the right.

   >>> world_shear = wcs.toWorld(image_shear, image_pos=None, world_pos=None)
   

   Equivalent to shearToWorld.

posToWorld(image_pos, color=None, **kwargs)

Convert a position from image coordinates to world coordinates.

LAX-backend implementation of galsim.wcs.posToWorld().

Parameters:

• image_pos – The position in image coordinates

• color – For color-dependent WCS’s, the color term to use. [default: None]

• project_center – (Only valid for CelestialWCS) A CelestialCoord to use for projecting the result onto a tangent plane world system rather than returning a CelestialCoord. [default: None]

• projection – If project_center != None, the kind of projection to use. See CelestialCoord.project for the valid options. [default: ‘gnomonic’]

Original GalSim Documentation

This is equivalent to wcs.toWorld(image_pos).

Returns:

world_pos

profileToWorld(image_profile, image_pos=None, world_pos=None, color=None, flux_ratio=1.0, offset=(0, 0))

Convert a profile from image coordinates to world coordinates.

LAX-backend implementation of galsim.wcs.profileToWorld().

Parameters:

• image_profile – The profile in image coordinates to transform.

• image_pos – The image coordinate position (for non-uniform WCS types)

• world_pos – The world coordinate position (for non-uniform WCS types)

• color – For color-dependent WCS’s, the color term to use. [default: None]

• flux_ratio – An optional flux scaling to be applied at the same time. [default: 1]

• offset – An optional offset to be applied at the same time. [default: 0,0]

Original GalSim Documentation

This is equivalent to wcs.toWorld(image_profile, ...).

shearToWorld(image_shear, image_pos=None, world_pos=None, color=None)

Convert a shear measured in image coordinates to world coordinates

LAX-backend implementation of galsim.wcs.shearToWorld().

Parameters:

• image_shear – The shear in image coordinates to convert.

• image_pos – The image coordinate position (for non-uniform WCS types)

• world_pos – The world coordinate position (for non-uniform WCS types)

• color – For color-dependent WCS’s, the color term to use. [default: None]

Original GalSim Documentation

This is equivalent to wcs.toWorld(shear, ...).

Specifically, the input shear is taken to be defined such that +e1 means elongated along the x-axis, -e1 is along the y-axis, +e2 is along the y=x line, and -e2 is along y=-x.

If the WCS is a EuclideanWCS, then the returned shear is converted to the equivalent shear in u-v coordinates. I.e. +e1 is along the u-axis, etc.

If the WCS is a CelestialWCS, then the returned shear is converted to sky coordinates where North is up and West is to the right (as appropriate for looking up into the sky from Earth). I.e. +e1 is E-W, -e1 is N-S, +e2 is NW-SE, and -e2 is NE-SW. This is the convention used by many, but not all, codes and catalogs that use or report shears on the spherical sky.

Returns:

world_shear: The shear in world coordinates.

toImage(*args, **kwargs)

Convert from world coordinates to image coordinates

LAX-backend implementation of galsim.wcs.toImage().

Original GalSim Documentation

There are essentially three overloaded versions of this function here.

1. The first converts a position from world coordinates to image coordinates. If the WCS is a EuclideanWCS, the argument may be either a PositionD or PositionI argument. If it is a CelestialWCS, then the argument must be a CelestialCoord. It returns the corresponding position in image coordinates as a PositionD:

   >>> image_pos = wcs.toImage(world_pos)
   

   Equivalent to posToImage.

2. The second is nearly the same, but takes either u and v values or ra and dec values (depending on the kind of wcs being used) directly and returns x and y values. For this version, the inputs may be numpy arrays, in which case the returned values are also numpy arrays:

   >>> x, y = wcs.toImage(u, v)                 # For EuclideanWCS types
   >>> x, y = wcs.toImage(ra, dec, units=units) # For CelestialWCS types
   

   Equivalent to uvToxy or radecToxy.

3. The third converts a surface brightness profile (a GSObject) from world coordinates to image coordinates, returning the profile in image coordinates as a new GSObject. For non-uniform WCS transforms, you must provide either image_pos or world_pos to say where the profile is located so the right transformation can be performed. And optionally, you may provide a flux scaling to be performed at the same time:

   >>> image_profile = wcs.toImage(world_profile, image_pos=None, world_pos=None,
                                   flux_ratio=1, offset=(0,0))
   

   Equivalent to profileToImage.

4. The fourth converts a shear measurement (a Shear) from image coordinates to world coordinates. As above, for non-uniform WCS transforms, you must provide either image_pos or world_pos. If the wcs is a CelestialWCS, then the returned shear follows the convention used by TreeCorr (among others) for shear on a sphere, namely in the local coordinates where north is up and west is to the right.

   >>> world_shear = wcs.toWorld(image_shear, image_pos=None, world_pos=None)
   

   Equivalent to shearToImage.

posToImage(world_pos, color=None)

Convert a position from world coordinates to image coordinates.

LAX-backend implementation of galsim.wcs.posToImage().

Parameters:

• world_pos – The world coordinate position

• color – For color-dependent WCS’s, the color term to use. [default: None]

Original GalSim Documentation

This is equivalent to wcs.toImage(world_pos).

profileToImage(world_profile, image_pos=None, world_pos=None, color=None, flux_ratio=1.0, offset=(0, 0))

Convert a profile from world coordinates to image coordinates.

LAX-backend implementation of galsim.wcs.profileToImage().

Parameters:

• world_profile – The profile in world coordinates to transform.

• image_pos – The image coordinate position (for non-uniform WCS types)

• world_pos – The world coordinate position (for non-uniform WCS types)

• color – For color-dependent WCS’s, the color term to use. [default: None]

• flux_ratio – An optional flux scaling to be applied at the same time. [default: 1]

• offset – An optional offset to be applied at the same time. [default: 0,0]

Original GalSim Documentation

This is equivalent to wcs.toImage(world_profile, ...).

shearToImage(world_shear, image_pos=None, world_pos=None, color=None)

Convert a shear measured in world coordinates to image coordinates

LAX-backend implementation of galsim.wcs.shearToImage().

Parameters:

• world_shear – The shear in world coordinates to convert.

• image_pos – The image coordinate position (for non-uniform WCS types)

• world_pos – The world coordinate position (for non-uniform WCS types)

• color – For color-dependent WCS’s, the color term to use. [default: None]

Original GalSim Documentation

This is equivalent to wcs.toImage(shear, ...).

This reverses the process described in shearToWorld.

Returns:

image_shear: The shear in image coordinates.

local(image_pos=None, world_pos=None, color=None)

Return the local linear approximation of the WCS at a given point.

LAX-backend implementation of galsim.wcs.local().

Parameters:

• image_pos – The image coordinate position (for non-uniform WCS types)

• world_pos – The world coordinate position (for non-uniform WCS types)

• color – For color-dependent WCS’s, the color term for which to evaluate the local WCS. [default: None]

Original GalSim Documentation

Returns:

a LocalWCS instance.

jacobian(image_pos=None, world_pos=None, color=None)

Return the local JacobianWCS of the WCS at a given point.

LAX-backend implementation of galsim.wcs.jacobian().

Parameters:

• image_pos – The image coordinate position (for non-uniform WCS types)

• world_pos – The world coordinate position (for non-uniform WCS types)

• color – For color-dependent WCS’s, the color term for which to evaluate the local jacobian. [default: None]

Original GalSim Documentation

This is basically the same as local(), but the return value is guaranteed to be a JacobianWCS, which can be useful in some situations, since you can access the values of the 2x2 Jacobian matrix directly:

>>> jac = wcs.jacobian(image_pos)
>>> x,y = np.meshgrid(np.arange(0,32,1), np.arange(0,32,1))
>>> u = jac.dudx * x + jac.dudy * y
>>> v = jac.dvdx * x + jac.dvdy * y
>>> # ... use u,v values to work directly in world coordinates.

If you do not need the extra functionality, then you should use local() instead, since it may be more efficient.

Returns:

a JacobianWCS instance.

affine(image_pos=None, world_pos=None, color=None)

Return the local AffineTransform of the WCS at a given point.

LAX-backend implementation of galsim.wcs.affine().

Parameters:

• image_pos – The image coordinate position (for non-uniform WCS types)

• world_pos – The world coordinate position (for non-uniform WCS types)

• color – For color-dependent WCS’s, the color term for which to evaluate the local affine transform. [default: None]

Original GalSim Documentation

This returns a linearized version of the current WCS at a given point. It returns an AffineTransform that is locally approximately the same as the WCS in the vicinity of the given point.

It is similar to jacobian(), except that this preserves the offset information between the image coordinates and world coordinates rather than setting both origins to (0,0). Instead, the image origin is taken to be image_pos.

For non-celestial coordinate systems, the world origin is taken to be wcs.toWorld(image_pos). In fact, wcs.affine(image_pos) is really just shorthand for:

>>> wcs.jacobian(image_pos).withOrigin(image_pos, wcs.toWorld(image_pos))

For celestial coordinate systems, there is no well-defined choice for the origin of the Euclidean world coordinate system. So we just take (u,v) = (0,0) at the given position. So, wcs.affine(image_pos) is equivalent to:

>>> wcs.jacobian(image_pos).withOrigin(image_pos)

You can use the returned AffineTransform to access the relevant values of the 2x2 Jacobian matrix and the origins directly:

>>> affine = wcs.affine(image_pos)
>>> x,y = np.meshgrid(np.arange(0,32,1), np.arange(0,32,1))
>>> u = affine.dudx * (x-affine.x0) + jac.dudy * (y-affine.y0) + affine.u0
>>> v = affine.dvdx * (x-affine.x0) + jac.dvdy * (y-affine.y0) + affine.v0
>>> # ... use u,v values to work directly in sky coordinates.

As usual, you may provide either image_pos or world_pos as you prefer to specify the location at which to approximate the WCS.

Returns:

an AffineTransform instance

shiftOrigin(origin, world_origin=None, color=None)

Shift the origin of the current WCS function, returning the new WCS.

LAX-backend implementation of galsim.wcs.shiftOrigin().

Parameters:

• origin – The image coordinate position to use for what is currently treated as (0,0).

• world_origin – The world coordinate position to use at the origin. Only valid if wcs.isCelestial() == False. [default: None]

• color – For color-dependent WCS’s, the color term to use in the connection between the current origin and world_origin. [default: None]

Original GalSim Documentation

This function creates a new WCS instance (always a non-local WCS) that shifts the origin by the given amount. In other words, it treats the image position origin the same way the current WCS treats (x,y) = (0,0).

If the current WCS is a local WCS, this essentially declares where on the image you want the origin of the world coordinate system to be. i.e. where is (u,v) = (0,0). So, for example, to set a WCS that has a constant pixel size with the world coordinates centered at the center of an image, you could write:

>>> wcs = galsim.PixelScale(scale).shiftOrigin(im.center)

This is equivalent to the following:

>>> wcs = galsim.OffsetWCS(scale, origin=im.center)

For non-local WCS types, the origin defines the location in the image coordinate system should mean the same thing as (x,y) = (0,0) does for the current WCS. The following example should work regardless of what kind of WCS this is:

>>> world_pos1 = wcs.toWorld(PositionD(0,0))
>>> wcs2 = wcs.shiftOrigin(new_origin)
>>> world_pos2 = wcs2.toWorld(new_origin)
>>> # world_pos1 should be equal to world_pos2

Furthermore, if the current WCS is a EuclideanWCS (wcs.isCelestial() == False) you may also provide a world_origin argument which defines what (u,v) position you want to correspond to the new origin. Continuing the previous example:

>>> wcs3 = wcs.shiftOrigin(new_origin, new_world_origin)
>>> world_pos3 = wcs3.toWorld(new_origin)
>>> # world_pos3 should be equal to new_world_origin

Returns:

the new shifted WCS

withOrigin(origin, world_origin=None, color=None)

tree_flatten()

This function flattens the WCS into a list of children nodes that will be traced by JAX and auxiliary static data.

classmethod tree_unflatten(aux_data, children)

Recreates an instance of the class from flatten representation

classmethod from_galsim(galsim_wcs)

Create a jax_galsim WCS object from a galsim WCS object.

to_galsim()

Create a galsim WCS object from a jax_galsim WCS object.

class jax_galsim.PixelScale(scale)

Bases: LocalWCS

This is the simplest possible WCS transformation. It only involves a unit conversion from pixels to arcsec (or whatever units you want to take for your world coordinate system).

LAX-backend implementation of galsim.wcs.PixelScale().

Parameters:

scale – The pixel scale, typically in units of arcsec/pixel.

Original GalSim Documentation

The conversion functions are:

u = x * scale v = y * scale

A PixelScale is initialized with the command:

>>> wcs = galsim.PixelScale(scale)

property scale

The pixel scale

LAX-backend implementation of scale().

copy()

class jax_galsim.OffsetWCS(scale, origin=None, world_origin=None)

Bases: UniformWCS

This WCS is similar to PixelScale, except the origin is not necessarily (0,0) in both the image and world coordinates.

LAX-backend implementation of galsim.wcs.OffsetWCS().

Parameters:

• scale – The pixel scale, typically in units of arcsec/pixel.

• origin – Optional origin position for the image coordinate system. If provided, it should be a PositionD or PositionI. [default: PositionD(0., 0.)]

• world_origin – Optional origin position for the world coordinate system. If provided, it should be a PositionD. [default: galsim.PositionD(0., 0.)]

Original GalSim Documentation

The conversion functions are:

u = (x-x0) * scale + u0 v = (y-y0) * scale + v0

An OffsetWCS is initialized with the command:

>>> wcs = galsim.OffsetWCS(scale, origin=None, world_origin=None)

property scale

The pixel scale.

LAX-backend implementation of scale().

property origin

The image coordinate position to use as the origin.

LAX-backend implementation of origin().

property world_origin

The world coordinate position to use as the origin.

LAX-backend implementation of world_origin().

copy()

class jax_galsim.JacobianWCS(dudx, dudy, dvdx, dvdy)

Bases: LocalWCS

This WCS is the most general local linear WCS implementing a 2x2 Jacobian matrix.

LAX-backend implementation of galsim.wcs.JacobianWCS().

Parameters:

• dudx – du/dx

• dudy – du/dy

• dvdx – dv/dx

• dvdy – dv/dy

Original GalSim Documentation

The conversion functions are:

u = dudx x + dudy y v = dvdx x + dvdy y

A JacobianWCS has attributes dudx, dudy, dvdx, dvdy that you can access directly if that is convenient. You can also access these as a NumPy array directly with:

>>> J = jac_wcs.getMatrix()

Also, JacobianWCS has another method that other WCS classes do not have. The call:

>>> scale, shear, theta, flip = jac_wcs.getDecomposition()

will return the equivalent expansion, shear, rotation and possible flip corresponding to this transformation. See the docstring for that method for more information.

A JacobianWCS is initialized with the command:

>>> wcs = galsim.JacobianWCS(dudx, dudy, dvdx, dvdy)

property dudx

du/dx

LAX-backend implementation of dudx().

property dudy

du/dy

LAX-backend implementation of dudy().

property dvdx

dv/dx

LAX-backend implementation of dvdx().

property dvdy

dv/dy

LAX-backend implementation of dvdy().

getMatrix()

Get the Jacobian as a NumPy matrix:

LAX-backend implementation of galsim.wcs.getMatrix().

Original GalSim Documentation

numpy.array( [[ dudx, dudy ],

[ dvdx, dvdy ]] )

getDecomposition()

Get the equivalent expansion, shear, rotation and possible flip corresponding to this Jacobian transformation.

LAX-backend implementation of galsim.wcs.getDecomposition().

Original GalSim Documentation

A non-singular real matrix can always be decomposed into a symmetric positive definite matrix times an orthogonal matrix:

M = P Q

In our case, P includes an overall scale and a shear, and Q is a rotation and possibly a flip of (x,y) -> (y,x).

( dudx dudy ) = scale/sqrt(1-g1^2-g2^2) ( 1+g1 g2 ) ( cos(theta) -sin(theta) ) F ( dvdx dvdy ) ( g2 1-g1 ) ( sin(theta) cos(theta) )

where F is either the identity matrix, ( 1 0 ), or a flip matrix, ( 0 1 ).

( 0 1 ) ( 1 0 )

If there is no flip, then this means that the effect of:

>>> prof.transform(dudx, dudy, dvdx, dvdy)

is equivalent to:

>>> prof.rotate(theta).shear(shear).expand(scale)

in that order. (Rotation and shear do not commute.)

The decomposition is returned as a tuple: (scale, shear, theta, flip), where scale is a float, shear is a Shear, theta is an Angle, and flip is a bool.

copy()

class jax_galsim.AffineTransform(dudx, dudy, dvdx, dvdy, origin=None, world_origin=None)

Bases: UniformWCS

This WCS is the most general linear transformation. It involves a 2x2 Jacobian matrix and an offset. You can provide the offset in terms of either the image_pos (x0,y0) where (u,v) = (0,0), or the world_pos (u0,v0) where (x,y) = (0,0). Or, in fact, you may provide both, in which case the image_pos (x0,y0) corresponds to the world_pos (u0,v0).

LAX-backend implementation of galsim.wcs.AffineTransform().

Parameters:

• dudx – du/dx

• dudy – du/dy

• dvdx – dv/dx

• dvdy – dv/dy

• origin – Optional origin position for the image coordinate system. If provided, it should be a PositionD or PositionI. [default: PositionD(0., 0.)]

• world_origin – Optional origin position for the world coordinate system. If provided, it should be a PositionD. [default: PositionD(0., 0.)]

Original GalSim Documentation

The conversion functions are:

u = dudx (x-x0) + dudy (y-y0) + u0 v = dvdx (x-x0) + dvdy (y-y0) + v0

An AffineTransform has attributes dudx, dudy, dvdx, dvdy, x0, y0, u0, v0 that you can access directly if that is convenient.

An AffineTransform is initialized with the command:

>>> wcs = galsim.AffineTransform(dudx, dudy, dvdx, dvdy, origin=None, world_origin=None)

property dudx

du/dx

LAX-backend implementation of dudx().

property dudy

du/dy

LAX-backend implementation of dudy().

property dvdx

dv/dx

LAX-backend implementation of dvdx().

property dvdy

dv/dy

LAX-backend implementation of dvdy().

property origin

The image coordinate position to use as the origin.

LAX-backend implementation of origin().

property world_origin

The world coordinate position to use as the origin.

LAX-backend implementation of world_origin().

copy()

class jax_galsim.ShearWCS(scale, shear)

Bases: LocalWCS

This WCS is a uniformly sheared coordinate system.

LAX-backend implementation of galsim.wcs.ShearWCS().

Parameters:

• scale – The pixel scale, typically in units of arcsec/pixel.

• shear – The shear, which should be a Shear instance.

Original GalSim Documentation

The shear is given as the shape that a round object has when observed in image coordinates.

The conversion functions in terms of (g1,g2) are therefore:

x = (u + g1 u + g2 v) / scale / sqrt(1-g1**2-g2**2) y = (v - g1 v + g2 u) / scale / sqrt(1-g1**2-g2**2)

or, writing this in the usual way of (u,v) as a function of (x,y):

u = (x - g1 x - g2 y) * scale / sqrt(1-g1**2-g2**2) v = (y + g1 y - g2 x) * scale / sqrt(1-g1**2-g2**2)

A ShearWCS is initialized with the command:

>>> wcs = galsim.ShearWCS(scale, shear)

The Shear transformation conserves object area, so if the input scale == 1 then the transformation represented by the ShearWCS will conserve object area also.

property scale

The pixel scale.

LAX-backend implementation of scale().

property shear

The applied Shear.

LAX-backend implementation of shear().

copy()

tree_flatten()

This function flattens the WCS into a list of children nodes that will be traced by JAX and auxiliary static data.

classmethod tree_unflatten(aux_data, children)

Recreates an instance of the class from flatten representation

class jax_galsim.OffsetShearWCS(scale, shear, origin=None, world_origin=None)

Bases: UniformWCS

This WCS is a uniformly sheared coordinate system with image and world origins that are not necessarily coincident.

LAX-backend implementation of galsim.wcs.OffsetShearWCS().

Parameters:

• scale – The pixel scale, typically in units of arcsec/pixel.

• shear – The shear, which should be a Shear instance.

• origin – Optional origin position for the image coordinate system. If provided, it should be a PositionD or PositionI. [default: PositionD(0., 0.)]

• world_origin – Optional origin position for the world coordinate system. If provided, it should be a PositionD. [default: PositionD(0., 0.)]

Original GalSim Documentation

The conversion functions are:

x = ( (1+g1) (u-u0) + g2 (v-v0) ) / scale / sqrt(1-g1**2-g2**2) + x0 y = ( (1-g1) (v-v0) + g2 (u-u0) ) / scale / sqrt(1-g1**2-g2**2) + y0

u = ( (1-g1) (x-x0) - g2 (y-y0) ) * scale / sqrt(1-g1**2-g2**2) + u0 v = ( (1+g1) (y-y0) - g2 (x-x0) ) * scale / sqrt(1-g1**2-g2**2) + v0

An OffsetShearWCS is initialized with the command:

>>> wcs = galsim.OffsetShearWCS(scale, shear, origin=None, world_origin=None)

property scale

The pixel scale.

LAX-backend implementation of scale().

property shear

The applied Shear.

LAX-backend implementation of shear().

property origin

The image coordinate position to use as the origin.

LAX-backend implementation of origin().

property world_origin

The world coordinate position to use as the origin.

LAX-backend implementation of world_origin().

copy()

tree_flatten()

This function flattens the WCS into a list of children nodes that will be traced by JAX and auxiliary static data.

classmethod tree_unflatten(aux_data, children)

Recreates an instance of the class from flatten representation

class jax_galsim.TanWCS(affine, world_origin, units=galsim.arcsec)

Bases:

This is a function that returns a GSFitsWCS object for a TAN WCS projection.

LAX-backend implementation of galsim.fitswcs.TanWCS().

Parameters:

• affine – An AffineTransform defining the transformation from image coordinates to the coordinates on the tangent plane.

• world_origin – A CelestialCoord defining the location on the sphere where the tangent plane is centered.

• units – The angular units of the (u,v) intermediate coordinate system. [default: galsim.arcsec]

Original GalSim Documentation

The TAN projection is essentially an affine transformation from image coordinates to Euclidean (u,v) coordinates on a tangent plane, and then a “deprojection” of this plane onto the sphere given a particular RA, Dec for the location of the tangent point. The tangent point will correspond to the location of (u,v) = (0,0) in the intermediate coordinate system.

Returns:

a GSFitsWCS describing this WCS.

class jax_galsim.FitsWCS(file_name=None, dir=None, hdu=None, header=None, compression='auto', text_file=False, suppress_warning=False)

Bases:

This factory function will try to read the WCS from a FITS file and return a WCS that will work. It tries a number of different WCS classes until it finds one that succeeds in reading the file.

LAX-backend implementation of galsim.fitswcs.FitsWCS().

🔪 JAX-GalSim - The Sharp Bits 🔪

JAX-GalSim only supports the GSFitsWCS class for celestial WCS types.

Parameters:

• file_name – The FITS file from which to read the WCS information. This is probably the usual parameter to provide. [default: None]

• dir – Optional directory to prepend to file_name. [default: None]

• hdu – Optionally, the number of the HDU to use if reading from a file. The default is to use either the primary or first extension as appropriate for the given compression. (e.g. for rice, the first extension is the one you normally want.) [default: None]

• header – The header of an open pyfits (or astropy.io) hdu. Or, it can be a FitsHeader object. [default: None]

• compression – Which decompression scheme to use (if any). See galsim.fits.read() for the available options. [default: ‘auto’]

• text_file – Normally a file is taken to be a fits file, but you can also give it a text file with the header information (like the .head file output from SCamp). In this case you should set text_file = True to tell GalSim to parse the file this way. [default: False]

• suppress_warning – Whether to suppress a warning that the WCS could not be read from the FITS header, so the WCS defaulted to either a PixelScale or AffineTransform. [default: False] (Note: this is (by default) set to True when this function is implicitly called from one of the galsim.fits.read* functions.)

Original GalSim Documentation

If none of them work, then the last class it tries, AffineTransform, is guaranteed to succeed, but it will only model the linear portion of the WCS (the CD matrix, CRPIX, and CRVAL), using reasonable defaults if even these are missing. If you think that you have the right software for one of the WCS types, but FitsWCS still defaults to AffineTransform, it may be helpful to update your installation of astropy and/or starlink (if you don’t already have the latest version).

Note: The list of classes this function will try may be edited, e.g. by an external module that wants to add an additional WCS type. The list is galsim.fitswcs.fits_wcs_types.

class jax_galsim.GSFitsWCS(file_name=None, dir=None, hdu=None, header=None, compression='auto', origin=None, _data=None)

Bases: CelestialWCS

This WCS uses a GalSim implementation to read a WCS from a FITS file.

LAX-backend implementation of galsim.fitswcs.GSFitsWCS().

🔪 JAX-GalSim - The Sharp Bits 🔪

The JAX-GalSim version of this class does not raise errors if inverting the WCS to map ra,dec to (x,y) fails. Instead it returns NaNs.

Parameters:

• file_name – The FITS file from which to read the WCS information. This is probably the usual parameter to provide. [default: None]

• dir – Optional directory to prepend to file_name. [default: None]

• hdu – Optionally, the number of the HDU to use if reading from a file. The default is to use either the primary or first extension as appropriate for the given compression. (e.g. for rice, the first extension is the one you normally want.) [default: None]

• header – The header of an open pyfits (or astropy.io) hdu. Or, it can be a FitsHeader object. [default: None]

• compression – Which decompression scheme to use (if any). See galsim.fits.read() for the available options. [default: ‘auto’]

• origin – Optional origin position for the image coordinate system. If provided, it should be a PositionD or PositionI. [default: None]

Original GalSim Documentation

It doesn’t do nearly as many WCS types as the other options, and it does not try to be as rigorous about supporting all possible valid variations in the FITS parameters. However, it does several popular WCS types properly, and it doesn’t require any additional python modules to be installed, which can be helpful.

Currrently, it is able to parse the following WCS types: TAN, STG, ZEA, ARC, TPV, TNX

A GSFitsWCS is initialized with one of the following commands:

>>> wcs = galsim.GSFitsWCS(file_name=file_name)  # Open a file on disk
>>> wcs = galsim.GSFitsWCS(header=header)        # Use an existing pyfits header

Also, since the most common usage will probably be the first, you can also give a file name without it being named:

>>> wcs = galsim.GSFitsWCS(file_name)

In addition to reading from a FITS file, there is also a factory function that builds a GSFitsWCS object implementing a TAN projection. See the docstring of TanWCS for more details.

tree_flatten()

This function flattens the WCS into a list of children nodes that will be traced by JAX and auxiliary static data.

classmethod tree_unflatten(aux_data, children)

Recreates an instance of the class from flatten representation

property origin

The origin in image coordinates of the WCS function.

LAX-backend implementation of origin().

copy()