V4::Xforms - Transformation formulae for 4-vectors
Methods and functions for converting 4-vectors between coordinate systems. These routines all take a standard set of inputs and make specific, direct conversions between coordinate systems. They are intended to be used primarily within V4, and hence aren't fully protected against malicious input. Furthermore, they don't keep proper track of all the coordinate-system labeling that makes v4 useful -- only coordinate units are updated. Look in V4 for actual user-level methods.
use V4; # Normal routines use Xform; # magic happens here
Local version of Math::Units::convert just puts the Math::Units version in an eval to hide the results of Croak (returns undef on error).
Grab coordinate indirection indices or defaults from a hash ref. Used internally by the various conversions.
Convert generic spherical to Cartesian coordinates $sph =
Sph2Cart($coords,{options});
Coord: Interpretation (input) Interpretation (output) 0: time (left alone) time 1: longitude (angle) X [ ALL 3 2: latitude (angle) Y are the 3: radius (arb.) Z same... ]
The pole points along the Z axis; the central meridian (0 longitude) is through the X axis; and the Y axis forms a right-handed coordinate system.
History: Ported from v4xsph2cart.pro, CED 30-Mar-2000
Convert generic Cartesian to spherical coordinates
$sph = Cart2Sph($coords,{options});
Coord: Interpretation (input) Interpretation (output)
0: time (left alone) (left alone)
1: X [ All 3 longitude (angle)
2: Y must be latitude (angle)
3: Z interconvertible ] radius (units of X)
See Sph2Cart for the inverse transform.
History: Ported from V4xcart2sph.pro, CED 31-Mar-2000
Convert between Heliographic Cartesian and Offset Cartesian coordinates.
$foo = offset_cartesian($coords,{parameters});
Coord: Interpretation (input) Interpretation (output)
0: time (left alone) (left alone)
1: X [ All 3 longitude (angle)
2: Y must be latitude (angle)
3: Z interconvertible ] radius (units of X)
System parameters are indexed by hash:
ORIGIN The origin of the offset system, in HC coordinates
(this is a string to be eval'ed to get the V4 back --
a workaround to the PDL-in-header problem).
Z_ORIG If set, then the reference angle for the ROT
keyword points directly away from the origin of the
original system (to match Heliographic Cartesian -- Z
toward the viewer!). If it exists, the ROT matrix is
applied to the origin-facing system.
ROT A 3-list containing the three rotation angles about
X, Y, Z (in that order) to get from orig. to offset coords.
Converts from a derived cartesian coordinate system to the cartesian system from which it is derived. First rotates using the Euler angles in the sys_params entry in the V4's header, then offsets back to the origin of the original coordinate system. The information in the sys_params field of the input V4's header is used for the Euler angles and offset.
If the sys_params field includes ``Z_ORIG'' then an initial rotation is applied that points the Z axis directly AWAY from the origin of the original system, reversing the X axis from its usual sense as well. This is the Right Thing to do for perspective transformations (where you want +Z to be toward the object and away from the observer in the observer's coordinates, but where +Z in the object's coordinates generally points toward the observer).
At the moment, unoffset_cartesian ONLY takes you back to the Heliographic Cartesian system; but the mathematics are general and it should be expanded to handle other systems as well. (The output ought to be in the coordinate system used by the ORIGIN field).
$cart = unoffset_cartesian($coords,{options});
Coord: Interpretation (input) Interpretation (output) 0: time (left alone) time 1-3: input "X","Y","Z" Output "X","Y","Z"
Input header information:
$coords->gethdr->{sys_params}->{Z_ORIG} :
If this field is *defined*, then the Euler angles are
referred to an initial orientation where the -Z axis of the
derived system points directly toward the origin of the
main system, X is nearly reversed, and Y is nearly the same
as its original configuration.
$coords->gethdr->{sys_params}->{ROT} :
Contains the Euler angles used to generate the rotated
derived system. They're in degrees, and (because this
is the UNoffset routine) applied in reverse order and
direction (i.e. [30,20,10] yields a 10 degree CCW rotation
about the Z axis, followed by 20 degrees CCW about the
*new* Y axis, and 20 degrees CCW about the *newer* X axis.
0: Rotation about the X axis
1: Rotation about the Y axis
2: Rotation about the Z axis
$coords->gethdr->{sys_params}->{ORIGIN} :
A V4 containing the origin of the derived system. Because
header-nested PDLs are currently broken, this is currently
a string that evaluates to the correct V4; it needs fixing
once the reference problem is fixed.
Converts Cartesian coordinates to the equi-angular azimuthal spherical projection. (in EQA projection, the pole points along the ``Z'' axis, the [x0,x1]-azimuth is the same as the [X,Y]-azimuth, and radial distance in the [x0,x1]-plane is the same as the subtended angle between the point and the ``Z'' axis. This is the system used by fisheye lenses.) The first two coordinates are angular, in degrees, and the last coordinate is the radius.
$eqa = cart2eqa($coords,[{options}]);
Coord: Interpretation (input) Interpretation (output)
0: time (left alone) time
1: "X" projection-x
2: "Y" projection-y
3: "Z" radius from origin
History: Written 21-Apr-2000, CED, v. 0.1 (not yet tested!)
Converts equi-angular azimuthal coordinates to Cartesian coordinates. (See Cart2EQA for a description of the EQA projection).
$eqa = cart2eqa($coords,[{options}]);
Coord: Interpretation (input) Interpretation (output)
0: time (left alone) time
1: projection-x X
2: projection-y Y
3: radius Z
History: Written 21-Apr-2000, CED, v. 0.5
Convert from Earth Range Solar coordinates to Solar Cartesian coordinates. (ERS is spherical based at Earth, with Z axis along the Earth-Sun line, and is a LEFT handed spherical coordinate system, by observing convention (west is positive-X; north is positive-Y).
Coord: Interpretation (input) Interpretation (output) 0: time (left alone) time 1: W angle (angle) W fr. Sun ctr 2: N angle (angle) N fr. Sun ctr 3: radius (arb.) Toward Earth
Convert from Solar Cartesian coordinates to Earth Range Solar coordinates. (See ERS2Cart for details) Because the ``B'' angle is handy, we also allow conversion from HC->ERS with a special, magic extra parameter.
Convert from Solar Cartesian to Heliographic Cartesian coordinates. This is a simple rotation by the ``B'' angle. To save namespace, the routine works both directions -- you feed it a multiplier on the angle. To go from HC to SCart, you feed in a -1.