Coordinate Systems

Batoid uses coordinate systems to track the positions and orientations of rays and surfaces. By using coordinate systems, one only ever has to define how surfaces behave when their vertexes are at the origin (0,0,0); relocating the surface to a non-origin vertex is accomplished by transforming coordinates.

There are two parts to a coordinate system in batoid:

• the origin, which specifies in global coordinates to the location of (0, 0, 0) in local coordinates, and

• the orientation, which specifies how the local x, y, and z axes are rotated with respect to the global axes.

class batoid.CoordSys(origin=None, rot=None)

A coordinate system against which to measure surfaces or rays.

Coordinate systems consist of an origin and a rotation. The origin attribute specifies where in 3D space the current coordinate system’s origin lands in the global coordinate system. The rotation rot specifies the 3D rotation matrix to apply to the global coordinate axes to yield the axes of the this coordinate system.

Parameters:

• origin (ndarray of float, shape (3,)) – Origin of coordinate system in global coordinates.

• rot (ndarray of float, shape (3, 3)) – Rotation matrix taking global axes into current system axes.

property xhat

Orientation of local x vector in global coordinates.

Type:

ndarray of float, shape (3,)

property yhat

Orientation of local y vector in global coordinates.

Type:

ndarray of float, shape (3,)

property zhat

Orientation of local z vector in global coordinates.

Type:

ndarray of float, shape (3,)

shiftGlobal(dr)

Return new CoordSys with origin shifted along global axes.

Parameters:

dr (ndarray of float, shape (3,)) – Amount to shift in meters.

Returns:

CoordSys

shiftLocal(dr)

Return new CoordSys with origin shifted along local axes.

Parameters:

dr (ndarray of float, shape (3,)) – Amount to shift in meters.

Returns:

CoordSys

toGlobal(v)

Convert vector(s) from local to global coordinates.

Parameters:

v (ndarray of float, shape (n, 3)) – Vector(s) in local coordinates.

Returns:

vv (ndarray of float, shape (n, 3)) – Vector in global coordinates.

toLocal(v)

Convert vector(s) from global to local coordinates.

Parameters:

v (ndarray of float, shape (n, 3)) – Vector(s) in global coordinates.

Returns:

vv (ndarray of float, shape (n, 3)) – Vector in local coordinates.

rotateGlobal(rot, rotCenter=(0, 0, 0), coordSys=None)

Return new CoordSys rotated with respect to global axes.

Parameters:

• rot (ndarray of float, shape (3, 3)) – Rotation matrix to apply.

• rotCenter (ndarray of float, shape (3,)) – Point about which to rotate.

• coordSys (CoordSys) – Coordinate system in which rotCenter is specified.

Returns:

CoordSys

rotateLocal(rot, rotCenter=(0, 0, 0), coordSys=None)

Return new CoordSys rotated with respect to local axes.

Parameters:

• rot (ndarray of float, shape (3, 3)) – Rotation matrix to apply.

• rotCenter (ndarray of float, shape (3,)) – Point about which to rotate.

• coordSys (CoordSys) – Coordinate system in which rotCenter is specified.

Returns:

CoordSys

class batoid.CoordTransform(fromSys, toSys)

Transformation between two coordinate systems.

Parameters:

• fromSys (CoordSys) – Origin coordinate systems.

• toSys (CoordSys) – Destination coordinate systems.

applyForward(rv)

Apply forward-direction transformation to RayVector.

Parameters:

rv (RayVector) – Rays to transform.

Returns:

transformed (RayVector) – Reference to input RayVector transformed in place.

applyReverse(rv)

Apply reverse-direction transformation to RayVector.

Parameters:

rv (RayVector) – Rays to transform.

Returns:

transformed (RayVector) – Reference to input RayVector transformed in place.

applyForwardArray(x, y, z)

Apply forward-direction transformation to ndarrays.

Parameters:

x, y, z (ndarray) – Coordinates to transform.

Returns:

xyz (ndarray) – Transformed coordinates.

Notes

Unlike applyForward, this method does not transform in-place, but returns a newly created ndarray.

applyReverseArray(x, y, z)

Apply reverse-direction transformation to ndarrays.

Parameters:

x, y, z (ndarray) – Coordinates to transform.

Returns:

xyz (ndarray) – Transformed coordinates.

Notes

Unlike applyReverse, this method does not transform in-place, but returns a newly created ndarray.

Angle Projections

For exact specification of ray directions, it’s convenient to use a two-dimensional projection. Batoid includes a number of such projections and deprojections:

batoid.utils.fieldToDirCos(u, v, projection='postel')

Convert field angle to direction cosines using specified projection.

Parameters:

• u, v (float) – Tangent plane coordinates in radians.

• projection ({‘postel’, ‘zemax’, ‘gnomonic’, ‘stereographic’, ‘lambert’, ‘orthographic’}) – Projection used to convert field angle to direction cosines.

Returns:

alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.

batoid.utils.dirCosToField(alpha, beta, gamma, projection='postel')

Convert direction cosines to field angle using specified projection.

Parameters:

• alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

• projection ({‘postel’, ‘zemax’, ‘gnomonic’, ‘stereographic’, ‘lambert’, ‘orthographic’}) – Projection used to convert direction cosines to field angle.

Returns:

u, v (float) – Tangent plane coordinates in radians.

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.

batoid.utils.gnomonicToDirCos(u, v)

Convert gnomonic tangent plane projection u,v to direction cosines.

Parameters:

u, v (float) – Gnomonic tangent plane coordinates in radians.

Returns:

alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.

batoid.utils.dirCosToGnomonic(alpha, beta, gamma)

Convert direction cosines to gnomonic tangent plane projection.

Parameters:

alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

Returns:

u, v (float) – Gnomonic tangent plane coordinates in radians.

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.

batoid.utils.postelToDirCos(u, v)

Convert Postel azimuthal equidistant tangent plane projection u,v to direction cosines.

Parameters:

u, v (float) – Postel tangent plane coordinates in radians.

Returns:

alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.

batoid.utils.dirCosToPostel(alpha, beta, gamma)

Convert direction cosines to Postel azimuthal equidistant tangent plane projection.

Parameters:

alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

Returns:

u, v (float) – Postel tangent plane coordinates in radians.

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.

batoid.utils.zemaxToDirCos(u, v)

Convert Zemax field angles u,v to direction cosines.

Parameters:

u, v (float) – Zemax field angles in radians.

Returns:

alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.

The Zemax field angle convention is not rotationally invariant. The z-direction cosine for (u, v) = (0, 1) does not equal the z-direction cosine for (u, v) = (0.6, 0.8).

batoid.utils.dirCosToZemax(alpha, beta, gamma)

Convert direction cosines to Postel azimuthal equidistant tangent plane projection.

Parameters:

alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

Returns:

u, v (float) – Postel tangent plane coordinates in radians.

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.

The Zemax field angle convention is not rotationally invariant. The z-direction cosine for (u, v) = (0, 1) does not equal the z-direction cosine for (u, v) = (0.6, 0.8).

batoid.utils.stereographicToDirCos(u, v)

Convert stereographic tangent plane projection u,v to direction cosines.

Parameters:

u, v (float) – Stereographic tangent plane coordinates in radians.

Returns:

alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.

batoid.utils.dirCosToStereographic(alpha, beta, gamma)

Convert direction cosines to stereographic tangent plane projection.

Parameters:

alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

Returns:

u, v (float) – Stereographic tangent plane coordinates in radians.

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.

batoid.utils.orthographicToDirCos(u, v)

Convert orthographic tangent plane projection u,v to direction cosines.

Parameters:

u, v (float) – Orthographic tangent plane coordinates in radians.

Returns:

alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.

batoid.utils.dirCosToOrthographic(alpha, beta, gamma)

Convert direction cosines to orthographic tangent plane projection.

Parameters:

alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

Returns:

u, v (float) – Orthographic tangent plane coordinates in radians.

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.

batoid.utils.lambertToDirCos(u, v)

Convert Lambert azimuthal equal-area tangent plane projection u,v to direction cosines.

Parameters:

u, v (float) – Lambert tangent plane coordinates in radians.

Returns:

alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.

batoid.utils.dirCosToLambert(alpha, beta, gamma)

Convert direction cosines to Lambert azimuthal equal-area tangent plane projection.

Parameters:

alpha, beta, gamma (float) – Direction cosines (unit vector projected onto x, y, z in order)

Returns:

u, v (float) – Lambert tangent plane coordinates in radians.

Notes

The tangent plane reference is at (u,v) = (0,0), which corresponds to (alpha, beta, gamma) = (0, 0, -1) (a ray coming directly from above). The orientation is such that vx (vy) is positive when u (v) is positive.