class Platform(observation_policy: PositionAndOrientationArray = None, platform_locator: PlatformLocation = None)

The purpose of the Platform class is to capture the details of the physical platform carrying an instrument. Common examples of platforms used in atmospheric research are spacecraft, aircraft, balloons and ground-based sites. There are a myriad of details surrounding real platforms but the Platform class’s only concern is to generate a list of instrument time, location and rotation matrices that properly orient Instrument Control Frame (ICF) for each simulated measurement. This list of platform state information is internally generated and then passed onto the next stage of analysis or retrieval.

The general form of usage is to perform the following steps,

1. Optional. Specify how an instrument is mounted on the platform. This defines the Instrument Control Frame (ICF).

2. Specify the universal times for a set of measurements

3. Specify the position of the platform for a set of measurements using a variety of positioning techniques, see Positioning Technique and add_measurement_set

4. Specify the orientation of the platform for a set of measurements using a variety of orientation techniques, see Platform Pointing Techniques and add_measurement_set.

5. The orientations define the Platform Control Frame (PCF) and the positions define the Geodetic Control Frame (GCF).

6. Create the internal PositionAndOrientationArray for the measurement set, see make_observation_policy.

7. Convert the PositionAndOrientationArray to arrays of position and instrument look vectors suitable for retrieval code.

Attributes:

icf_to_ecef_rotation_matrices

Returns the platform rotation matrices, one matrix for each RT calculation

numsamples

Returns the number of samples/exposures in the current observation set

observation_policy

Returns the current internal PositionAndOrientationArray object.

platform_ecef_positions

Returns the position of the platform for each RT calculation

platform_locator

Sets and gets the internal PlatformLocation object.

platform_pointing

Gets the internal PlatformPointing object.

Methods

add_current_platform_state()	Fetches the current platform position and orientation and uses this as a new sample in the observation policy.
add_measurement_set(utc, platform_position, ...)	Adds a set of N measurements definitions to the internal list of measurement sets.
clear_states()	Clears all of the internally cached measurement states.
icf_to_ecef(los_icf)	Returns the lines of sight in geographic geocentric ECEF coordinates of the lines of sight specified in the instrument control frame.
make_ecef_position_and_lookvector([...])
make_optical_geometry()	Takes all the measurements from previous calls to add_measurement_set and returns them as a list of OpticalGeometry values which can be used by various retrievals.
make_position_and_orientation_array()	Takes all the measurements from previous calls to add_measurement_set and converts them into a list of measurements stored inside the internal instance of PositionAndOrientationArray object.

__init__(observation_policy: PositionAndOrientationArray = None, platform_locator: PlatformLocation = None)

Parameters:

platform_locator: PlatformLocation

Default None. This optional parameter can be used to add a platform location object such as a satellite, aircraft or ground site.

observation_policy: PositionAndOrientationArray

Default None. This optional parameter can use an existing PositionAndOrientationArray object rather than create a new empty instance.

add_current_platform_state() → int

Fetches the current platform position and orientation and uses this as a new sample in the observation policy.

Returns:

int

The number of samples in the current observation policy

add_measurement_set(utc, platform_position, platform_orientation, icf_orientation=None)

Adds a set of N measurements definitions to the internal list of measurement sets. An overview of position and orientation techniques is given in Overview.

Parameters:

utc:Array, sequence or scalar of string, float, datetime or datetime64

The set of universal times for the set of measurements. The array should be an array or sequence of any type that can be coerced by package sktimeutils into a numpy array (N,) of datetime64. This includes strings, datetime, datetime64. Floating point values are also converted and are assumed to represent modified julian date. The number of universal time values defines the number of measurements in this set unless it is a scalar. In this case the time value is duplicated into an array with the same number of measurements as parameter observer_positions. All ali_elements of the array should be of the same type and should represent universal time. Be wary of using datetime objects with explicit time-zones.

observer_positions: Tuple[str, sequence]

A two element tuple. The first element specifies the Positioning Technique to be used to position the platform. The second element of the tuple is an array of arrays of float. The array of arrays can be any Python, list of lists, tuples or arrays that can be coerced into a two dimensional array of shape (N, numparams) where N is the number of measurements and must match the size of the utc parameter parameters and numparams is the number of parameters required by the chosen Positioning Technique. The second element of the tuple can be dropped if the positioning technique is from_platform.

platform_orientation:

A three element tuple. The first element of the tuple is a string that specifies the Platform Pointing Techniques. The second element of the tuple specifies Roll Control and the third element is an array of arrays of float. The array of arrays can be any Python, list of lists, tuples or arrays that can be coerced into a two dimensional array of shape (N, numparams) where N is the number of measurements and must match the size of the utc parameter and numparams is the number of parameters required by the chosen Platform Pointing Techniques

instrument_internal_rotation:

Optional. An array that specifies the internal rotation of the instrument within the Instrument Control Frame (ICF). This is intended to provide support for tilting mirrors and turntables attached to the instrument that redirect the instrument boresight independently of the platform. The array specifies the azimuth, elevation and roll of the instrument boresight in the Instrument Control Frame (ICF). The array is a sequence or array that can be sensibly coerced into an array of size (N,2) or (N,3) where N is the number of measurements. N can be 1 in which case the array size is broadcast to match the number of measurements inferred from the other parameters. Elements [:,0] is the azimuth in degrees of the instrument boresight in the instrument control frame, left handed rotation around \(\hat{z}_{ICF}\). Elements [:,1] are the elevation in degrees of the instrument boresight in the instrument control frame, left handed rotation around the rotated \(\hat{y}_{ICF}\) axis. Elements[:,2], which are are optional, are the roll of the instrument boresight in degrees, right handed rotation around the rotated \(\hat{x}_{ICF}\) axis. The roll defaults to 0.0 if not supplied.

clear_states()

Clears all of the internally cached measurement states. This should be called when re-using a platform object to create a new measurement set.

icf_to_ecef(los_icf: ndarray) → ndarray

Returns the lines of sight in geographic geocentric ECEF coordinates of the lines of sight specified in the instrument control frame.

Parameters:

los_icfnp.ndarray( 3,Nlos)

A 2-D array of N unit vectors expressed in the instrument control frame

Returns:

np.ndarray (3,Nlos, Ntime)

A numpy array is returned with the 3 element geographic, geocentric, line of sight unit vector for each input lines of sight and each time in the current observation set.

property icf_to_ecef_rotation_matrices: List[RotationMatrix]

Returns the platform rotation matrices, one matrix for each RT calculation

Returns:

np.ndarray(3,N)

The X,Y,Z icf_to_ecef_rotation_matrices of the platform.

make_optical_geometry() → List[OpticalGeometry]

Takes all the measurements from previous calls to add_measurement_set and returns them as a list of OpticalGeometry values which can be used by various retrievals. The internal PositionAndOrientationArray is also created at this time using method make_observation_policy.

make_position_and_orientation_array() → PositionAndOrientationArray

Takes all the measurements from previous calls to add_measurement_set and converts them into a list of measurements stored inside the internal instance of PositionAndOrientationArray object. This list of measurements can be converted to other formats, such as OpticalGeometry required by other parts of the skretrieval package. This method clears all the measurements that have been previously added.

property numsamples: int

Returns the number of samples/exposures in the current observation set

Returns:

int

The number of samples in the current observation set

property observation_policy: PositionAndOrientationArray

Returns the current internal PositionAndOrientationArray object.

Returns:

PositionAndOrientationArray

Returns the current internal PositionAndOrientationArray object.

property platform_ecef_positions: ndarray

Returns the position of the platform for each RT calculation

Returns:

np.ndarray(3,N)

The X,Y,Z location of the platform for each RT calculation. The coordinates are in meters form the center of the Earth,

property platform_locator: PlatformLocation

Sets and gets the internal PlatformLocation object. This field is set to None by default but can be set to a valid class if the user wishes to use a specialized class to get the platform position or orientation as a function of time.

property platform_pointing: PlatformPointing

Gets the internal PlatformPointing object. This object manages all the rotation matrices used to transform between various frames.

• Positioning Technique
• Platform Pointing Techniques
• Roll Control

Internal Classes

PositionAndOrientationArray

class PositionAndOrientationArray

Stores the array of platform position and orientations used for each instantaneous observation in Platform. This object internally stores a list of platform orientation and states created by calls to

• add_current_state to add a new sample to the policy object

• clear to clear the current list of samples in the policy object

The instrument model uses the current list of platform states in the platform’s PositionAndOrientationArray as one of its inputs to the radiative transfer engine. The user must add at least one platform state to the PositionAndOrientationArray for the radiative transfer to calculate anything.

Real observation policies for real instruments may be much more detailed than simply saving platform position, orientation and time. For example, mirrors and filters may need to be adjusted, integration times and detector binning modes may need to be varied. These aspects are beyond the scope of the platform’s observation policy and are left for the user to manage and implement.

Methods

add_current_state(platform_attitude)	Adds the current state of the platform to the observation policy.
clear()	Clears the current list of platform states inside the observation policy.
ecef_positions()	Returns the geocentric geographic (ECEF) position of the platform for each sample in the observation set.
icf_to_ecef_rotation_matrix()	Returns the orientation of the platform for each sample in the observation set.
numsamples_in_observationset()	Returns the number of samples in this observation policy
to_ecef_position_and_look([icf_lookvectors, ...])	Converts the platform orientations defined in the PositionAndOrientationArray to a list of OpticalGeometry which can be used in retrieval code.
to_optical_geometry()	Converts the platform orientations defined in thos PositionAndOrientationArray to a list of OpticalGeometry which can be used in retrieval code.
utc()	Returns the UTC of each of the samples in the observation set.

add_current_state(platform_attitude: PlatformPointing) → int

Adds the current state of the platform to the observation policy. A typical scenario is for the end-user to set the position, orientation and time of the platform using one of many available methods and to then capture the platform state for further use within the radiative transfer engine.

Parameters:

platform_attitude: PlatformPointing

The object used to define the platform position, orientation and time.

Returns:

int

The number of samples in the observation policy.

clear()

Clears the current list of platform states inside the observation policy. This method should be called before starting a new observation policy

ecef_positions()

Returns the geocentric geographic (ECEF) position of the platform for each sample in the observation set.

Returns:

np.ndarray( 3,Nt)

Returns the geographic geocentric position as an array of ECEF vectors, one three element column for each sample in the observation set. The position is specified in meters from the centre of the Earth.

icf_to_ecef_rotation_matrix()

Returns the orientation of the platform for each sample in the observation set.

Returns:

List[RotationMatrix]

Returns the rotation matrix for each sample. The rotation matric will convert Instrument Control Frame unit vectors to geocentric geographic unit vectors. The matrix equation is vgeo = R.R @ vicf

numsamples_in_observationset() → int

Returns the number of samples in this observation policy

Returns:

int

The number of samples in the observation policy.

to_ecef_position_and_look(icf_lookvectors=None, one_to_one: bool = False) → Tuple[ndarray, ndarray, ndarray]

Converts the platform orientations defined in the PositionAndOrientationArray to a list of OpticalGeometry which can be used in retrieval code. This conversion assumes the instrument is looking along the x axis of the Instrument Control Frame (ICF) the instrument control frame and the local_up used by the retrieval is in the direction of the Z axis in the Instrument Control Frame (ICF).

Returns:

Tuple[np.ndarray, np.ndarray, np.ndarray]

A three element storing (0) the observer ECEF X,Y,Z position, (1) the ECEF look vector away from the instrument/platform and (2) the UT ttime

to_optical_geometry() → List[OpticalGeometry]

Converts the platform orientations defined in thos PositionAndOrientationArray to a list of OpticalGeometry which can be used in retrieval code. This conversion assumes the instrument is looking along the x axis of the Instrument Control Frame (ICF) the instrument control frame and the local_up used by the retrieval is in the direction of the Z axis in the Instrument Control Frame (ICF).

Returns:

List[OpticalGeometry]

The list of measurement definitions used by retrieval code.

utc()

Returns the UTC of each of the samples in the observation set. The UTC is either an array of numpy.datetime64 values or an array of floats representing MJD. Note that the datetime64 are detected and converted to MJD inside the FrontEndRadianceGenerator before calling Sasktran.

---

Platform_Pointing

class PlatformPointing

A class used to manage the pointing requirements of an instrument mounted on a platform. The primary objective is to

• Mount an instrument on a platform, eg balloon, aircraft, satellite, ground.

• Place and orient the platform at a location in space, on the ground or in the atmosphere.

• Generate unit vectors at the front aperture of the instrument representing lines of sight and similar that can be used by the radiative transfer codes.

The PlatformPointing class generates rotation matrices to transform between the different standard control frames as well as methods to mount the instrument on the platform, position the platform and rotate the platform.

Methods

convert_gcf_to_ecef(v)	Converts vectors expressed in the geodetic control frame to geographic geocentric vectors using the current rotation matrices.
convert_icf_to_ecef(v)	Converts vectors expressed in the instrument coordinate frame to geographic geocentric ECEF vectors using the current rotation matrices.
convert_icf_to_gcf(v)	Converts vectors expressed in the instrument coordinate frame to geodetic control frame vectors using the current rotation matrices.
force_pcf_rotation_matrix(GEO)	Defines the rotation matrix applied to the platform control frame so the Instrument Control Frame (ICF) unit vectors axes are aligned to the ECEF unit-vectors passed in after the full stack of rotation matrices are applied.
get_icf_to_ecef_matrix()	Returns the rotation matrix that converts vectors expressed in the instrument control frame to vectors in the geographic geocentric control frame If you are inspecting the source code for this method note that the rotation matrices are applied in reverse order, ie.
local_south()	Returns the geocentric unit vector of south at the current location of the platform.
local_up()	Returns the geocentric unit vector of up at the current location of the platform.
local_west()	Returns the geocentric unit vector of west at the current location of the platform.
location()	returns the geocentric location of the platform.
mount_instrument_on_platform(...[, roll_degrees])	Mounts an instrument on a platform by setting up the azimuth, elevation and roll of the Instrument Control Frame (ICF) with respect to the Lab Control Frame (LCF).
orient_platform_in_space(yaw_degrees, ...)	Sets the platforms yaw, pitch and roll to orient the platform in space at its location.
reset_icf_rotation_matrices()	Resets the IRM and ICF_to_PCF matrices to unity.
rotate_instrument_in_icf(azimuth_degrees, ...)	Sets the instrument rotation matrix so it rotates the instrument control frame, \((\hat{x}_{ICF}, \hat{y}_{ICF}, \hat{z}_{ICF})\), through the given azimuth, elevation and roll angles.
set_platform_location([xyzt, latlonheightandt])	Sets the location and time of the platform to the given location and time.
utc()

convert_gcf_to_ecef(v: ndarray) → ndarray

Converts vectors expressed in the geodetic control frame to geographic geocentric vectors using the current rotation matrices.

Parameters:

vnp.ndarray

An array (3xN) of N vectors expressed in the geodetic control frame.

• v[0,:] is the \(\hat{x}_{GCF}\) component of each vector,

• v[1,:] is the \(\hat{y}_{GCF}\) component,

• v[2,:] is the \(\hat{z}_{GCF}\) component.

Returns:

np.ndarray

An array (3xN) of N vectors expressed in the geodetic control frame,

• v[0,:] is the \(\hat{x}_{ECEF}\) component,

• v[1,:] is the \(\hat{y}_{ECEF}\) component,

• v[2,:] is the \(\hat{z}_{ECEF}\) component.

convert_icf_to_ecef(v: ndarray) → ndarray

Converts vectors expressed in the instrument coordinate frame to geographic geocentric ECEF vectors using the current rotation matrices.

Parameters:

vnp.ndarray

An array (3xN) of N vectors expressed in the instrument control frame.

• v[0,:] is the \(\hat{x}_{ICF}\) component of each vector,

• v[1,:] is the \(\hat{y}_{ICF}\) component,

• v[2,:] is the \(\hat{z}_{ICF}\) component.

Returns:

np.ndarray

An array (3xN) of N vectors expressed in the geographic geocentric control frame,

• v[0,:] is the \(\hat{x}_{ECEF}\) component,

• v[1,:] is the \(\hat{y}_{ECEF}\) component,

• v[2,:] is the \(\hat{z}_{ECEF}\) component.

convert_icf_to_gcf(v: ndarray) → ndarray

Converts vectors expressed in the instrument coordinate frame to geodetic control frame vectors using the current rotation matrices.

Parameters:

vnp.ndarray

An array (3xN) of N vectors expressed in the instrument control frame.

• v[0,:] is the \(\hat{x}_{ICF}\) component of each vector,

• v[1,:] is the \(\hat{y}_{ICF}\) component,

• v[2,:] is the \(\hat{z}_{ICF}\) component.

Returns:

np.ndarray

An array (3xN) of N vectors expressed in the geodetic control frame,

• v[0,:] is the \(\hat{x}_{GCF}\) (West) component,

• v[1,:] is the \(\hat{y}_{GCF}\) (South) component ,

• v[2,:] is the \(\hat{z}_{GCF}\) (Up) component.

force_pcf_rotation_matrix(GEO: UnitVectors)

Defines the rotation matrix applied to the platform control frame so the Instrument Control Frame (ICF) unit vectors axes are aligned to the ECEF unit-vectors passed in after the full stack of rotation matrices are applied. Note this rotation is not applied to the Instrument Rotation Matrix (_ICF_to_LCF) as it is intended to force the primary boresight of the instrument control frame point towards a specific location.

The problem is a linear algebra problem where we have G=RX, where G is the 3x3 Unitvector array passed in, X is the initial 3x3 unit vectors in the instrument control frame and R is the stack of rotation matrices. The matrix R can be expanded and we get a matrix equation of the form (A )(PCF_to_GCF) ( B )= G where we know everything except PCF_to_GCF. Thus we get PCF_to_GCF = (A-1) G (B-1)

Parameters:

GEOUnitVectors

A 3x3 array of column unit vectors. These unit vectors specify the desired orientation of the instrument control frame vectors after rotation to the Geocentric Control Frame (ECEF).

get_icf_to_ecef_matrix() → RotationMatrix

Returns the rotation matrix that converts vectors expressed in the instrument control frame to vectors in the geographic geocentric control frame If you are inspecting the source code for this method note that the rotation matrices are applied in reverse order, ie. right-most or last array in the list is the first rotation applied and left-most or first in the list is the last rotation/operation.

Returns:

np.ndarray

An (3x3) rotation matrix. The array is used to transform vectors from the ICF instrument control frame to the ECEF geocentric control frame. The matrix should be applied as \(\boldsymbol{V_{GEO}} = \boldsymbol{R} @ \boldsymbol{V_{ICF}}\)

local_south()

Returns the geocentric unit vector of south at the current location of the platform. Only valid after a successful call to set_platform_location

local_up()

Returns the geocentric unit vector of up at the current location of the platform. Only valid after a successful call to set_platform_location

local_west()

Returns the geocentric unit vector of west at the current location of the platform. Only valid after a successful call to set_platform_location

location()

returns the geocentric location of the platform. Only valid after a successfull call to set_platform_location

mount_instrument_on_platform(azimuth_degrees: ndarray | float, elevation_degrees: ndarray | float, roll_degrees: ndarray | float = 0.0)

Mounts an instrument on a platform by setting up the azimuth, elevation and roll of the Instrument Control Frame (ICF) with respect to the Lab Control Frame (LCF). Note that we try to use fairly standard definitions of azimuth, elevation and roll. The laboratory defines a local X, Y, Z coordinate system. eg X is towards 0 degrees (or front) in a horizontal plane, Z is upwards and Y is in the horizontal plane and forms a right handed system towards the left/port.

azimuth is left handed rotation around Z. It is clockwise rotation when viewed from above and follows a compass. elevation is left handed rotation around Y. It is positive upwards and is 0 in the horizontal plane roll is right handed rotation around X.

Rotation are applied in the order Z, Y, X rotations in the order, azimuth first, elevation second and roll third,

• azimuth is 0.0 when \(\hat{x}_{ICF}\) is pointing along the fuselage towards the nose, i.e. it is parallel to \(\hat{x}_{PCF}\). It is positive towards startboard (right hand).

• elevation is 0.0 along the fuselage towards the nose when \(\hat{x}_{ICF}\) is parallel to \(\hat{x}_{PCF}\) and \(\hat{z}_{ICF}\) is pointing upwards. It is positive as \(\hat{x}_{ICF}\) tilts upwards.

• roll is 0.0 when \(\hat{y}_{ICF}\) is parallel to the wings pointing to port-side (left) and is anti-parallel to \(\hat{y}_{PCF}\). It is positive as \(\hat{y}_{ICF}\) tilts upwards and the aircraft leans to the right.

The instrument control frame is initally configured so the instrument is mounted with azimuth, elevation and roll all equal to 0: \(\hat{x}_{ICF}\) is parallel to \(\hat{x}_{PCF}\) and \(\hat{z}_{ICF}\) is anti-parallel to \(\hat{z}_{PCF}\)

Parameters:

azimuth_degreesarray[N] or float

The azimuth of the instrument boresight in the platform control frame in degrees. Azimuth is zero along the aircraft fuselage towards the nose and increases towards the right/starboard

elevation_degreesarray[N] or float

The elevation of the instrument boresight in the platform control frame in degrees. Elevation is 0.0 along the fuselage towards the nose and increases in the upward direction.

roll_degreesarray[N] or float

The right-handed roll in degrees of the instrument around the final resting point of the boresight, \(\hat{x}_{ICF}\), in the platform control frame. The rotation is a right-handed roll around the final. Default is 0.0

orient_platform_in_space(yaw_degrees: ndarray | float, pitch_degrees: ndarray | float, roll_degrees: ndarray | float)

Sets the platforms yaw, pitch and roll to orient the platform in space at its location. The yaw, pitch and roll are applied in a geodetic system so angles are always about the local geodetic system regardless of the platform location and the values stay in effect until explicitly changed.

This function is typically not required in simulators (although it can be set if you wish) as the platform pointing in these cases is overridden by the need to look at a “simulated” target location. The function is useful for attitude solutions from actual platforms where yaw, pitch and roll are a common method of specifying platform orientation

This function will orient the entire platform in space. The platform control frame is initially set so the interpretation of yaw, pitch and roll are sensible, see Platform Control Frame (PCF).

Parameters:

yaw_degreesarray[N] or float

The yaw or geographic bearing of the platform control frame in degrees. This is a geographic bearing, N= 0, E= 90, S= 180, W = 270.

pitch_degreesarray[N] or float

The pitch of the platform control frame in degrees. Pitch is right-handed rotation around the starboard pointing \(\hat{y}_{PCF}\). A positive pitch will tip the \(\hat{x}_{PCF}\) unit vector upwards. Negative values will tip it downwards.

roll_degreesarray[N] or float

The roll of the platform control frame in degrees. Roll is the right-handed rotation around \(\hat{x}_{PCF}\) after yaw and pitch have been applied. A pilot in a plane looking out of the nose along \(\hat{x}_{PCF}\) will roll to his right side, (right shoulder falls, left shoulder rises) assuming he is not flying upside down.

reset_icf_rotation_matrices()

Resets the IRM and ICF_to_PCF matrices to unity.

rotate_instrument_in_icf(azimuth_degrees: ndarray | float, elevation_degrees: ndarray | float, roll_degrees: ndarray | float = 0.0)

Sets the instrument rotation matrix so it rotates the instrument control frame, \((\hat{x}_{ICF}, \hat{y}_{ICF}, \hat{z}_{ICF})\), through the given azimuth, elevation and roll angles. This method is intended to simulate tilting mirrors and rotation stages attached to the instrument. The rotation is applied in the order, azimuth, elevation, roll.

Parameters:

azimuth_degreesarray[N] or float

The azimuth of the instrument boresight in the platform control frame in degrees. Azimuth is left handed rotation around \(\hat{z}_{ICF}\).

elevation_degreesarray[N] or float

The elevation of the instrument boresight in the platform control frame in degrees. Elevation is a left-handed rotation around \(\hat{y}_{ICF}\).

roll_degreesarray[N] or float

The roll in degrees of the instrument. It is a right-handed rotation around \(\hat{x}_{ICF}\). Default is 0.0

set_platform_location(xyzt: Tuple[ndarray | float, ndarray | float, ndarray | float, ndarray | datetime64] = None, latlonheightandt: Tuple[ndarray | float, ndarray | float, ndarray | float, ndarray | datetime64] = None)

Sets the location and time of the platform to the given location and time. The methods supports setting just one location or an array of locations. The array option allows it to be used reasonably efficiently for instruments or simulations that need to process many (tens or hundreds of thousands of) locations.

The location is used to configure the internal GCF_to_ECEF rotation matrix that transforms local geodetic look vectors into global ECEF X,Y,Z look vectors.

The caller can choose to specify the location as either global geocentric ECEF coordinates using keyword option xyzt or as geodetic latitude, longitude and altitude using keyword option latlonheight. The caller must exlicitly set one of these options

Parameters:

xyzt: Tuple[float, float, float, np.datetime64] or Tuple[ array[N], array[N], array[N], array[N]]

A 4 element tuple that specifies the platform location and time with X, Y, Z ECEF coordinates in meters and UTC

1. ECEF X geocentric coordinate in meters, either scalar or array[N]

2. ECEF Y geocentric corodinate in meters, either scalar or array[N]

3. ECEF Z geocentric coordinate in meters, either scalar or array[N]

4. UTC in any format that sktimeutils.ut_to_datetime64 supports, either scalar or array[N]

latlonheight: Tuple[float, float, float, np.datetime64] or Tuple[ array[N], array[N], array[N], array[N]]

A 4 element tuple that specifies the platform location with Geodetic coordinates X, Y, Z ECEF geocentric location of the platform in meters.

1. Geodetic latitude in degrees, either scalar or array[N]

2. Geodetic longitude in degrees, either scalar or array[N]

3. Geodetic altitude in meters above sea level, either scalar or array[N]

4. UTC in any format that sktimeutils.ut_to_datetime64 supports, either scalar or array[N]

Returns:

True if successful otherwise False.

---

PlatformLocation

class PlatformLocation

The base class used to specify the location and velocity, if appropriate, of platforms that carry instruments. This covers spacecraft, aircraft, balloons and ground sites. The class exposes two abstract functions that all classes derived form PlatformLocation must override,

1. update_position.

2. position

In addition, platforms that move can override,

1. velocity. Optional, defaults to [0.0, 0.0, 0.0]

This class also provides the platform position as an astropy EarthLocation which allows latitude, longitude and height to be determined.

1. earth_location

2. lat_lon_height.

Attributes:

earth_location

Returns the current position of the platform as an Astropy EarthLocation.

lat_lon_height

Returns the current platform location as a 3 element array of geodetic coordinates, latitude in degrees, longitude in degrees and height in meters.

position

Returns the geographic, ITRF, geocentric location calculated in the last call to update_position.

velocity

Returns the geocentric velocity calculated in the last call to update_position.

Methods

update_orientation(utc)	Updates the orientation of the at the given time and retursn an x,y,z ITRF unit vector.
update_position(utc)	Updates the geographic geocentric location of the platform at the given coordinated universal time and returns the new position.
update_velocity(utc)	Updates the geographic geocentric location of the platform at the given coordinated universal time and returns the new position.

property earth_location: EarthLocation

Returns the current position of the platform as an Astropy EarthLocation. This is a convenience function wrapped around position

Returns:

EarthLocation

Location of the platform as an astropy EarthLocation object.

property lat_lon_height: ndarray

Returns the current platform location as a 3 element array of geodetic coordinates, latitude in degrees, longitude in degrees and height in meters. This is a convenience function wrapped around position

Returns:

numpy.ndarray, Array[3,]

A 3 element array of [ latitude, longitude, height in meters]

abstract property position: ndarray

Returns the geographic, ITRF, geocentric location calculated in the last call to update_position. This is an abstract method and must be implemented in a derived classes.

Returns:

np.ndarray(3,)

A three element array storing the X,Y,Z geocentric location (ITRF ecef, wgs84) of the platform. All numbers are in meters.

abstract update_orientation(utc: datetime | datetime64) → Tuple[ndarray, ndarray, ndarray] | None

Updates the orientation of the at the given time and retursn an x,y,z ITRF unit vector.

Parameters:

utcdatetime

The time at which to update the location of the platform

Returns:

Tuple[ x:np.ndarray(3,), y:np.ndarray(3,), z:np.ndarray(3,) ]

A three element storing X,Y,Z unit vectors of the platform orientation. Returns None if there is an issue fetching the pointing data at the given time.

abstract update_position(utc: datetime | datetime64) → ndarray | None

Updates the geographic geocentric location of the platform at the given coordinated universal time and returns the new position. This is an abstract method and must be implemented in derived child classes.

Parameters:

utcdatetime

The time at which to update the location of the platform

Returns:

np.ndarray, Array[3]

The three element X,Y,Z geographic geocentric location of the platform

abstract update_velocity(utc: datetime | datetime64) → ndarray | None

Updates the geographic geocentric location of the platform at the given coordinated universal time and returns the new position. This is an abstract method and must be implemented in derived child classes.

Parameters:

utcdatetime

The time at which to update the location of the platform

Returns:

np.ndarray, Array[3]

The three element X,Y,Z geographic geocentric location of the platform

abstract property velocity: ndarray

Returns the geocentric velocity calculated in the last call to update_position. This may be implemented in derived child classes to override the default method which returns an array of zeros,

Returns:

np.ndarray, Array[3,]

The three element X,Y,Z geographic geocentric velocity of the platform. All numbers are in meters/second.

---

OrientationTechniques

class OrientationTechniques

A helper class that allows users to specify position and orientations using a set of position techniques and orientation techniques.

Methods

add_icf_look_vector_convertor(lookvectorype, ...)
add_measurement_set(utc, platform_position, ...)	Adds a set of measurements to the parent :class:~.Instrument`.
add_platform_orientation_convertor(...)
add_position_convertor(positiontype, ...)
clear()	Clears the current list of platform states inside the observation policy.
make_observation_set(platform)	Converts the internal list of measurements from previous calls to add_measurement_set into an an internally cached PositionAndOrientationArray.
num_measurements()	Returns the number of samples in this observation policy

add_measurement_set(utc: float | str | datetime64 | datetime | ndarray | Sequence[float | str | datetime64 | datetime | ndarray], platform_position: Tuple[str, Sequence | ndarray], platform_orientation: Tuple[str, str, Sequence | ndarray], icf_orientation: Tuple[str, str, Sequence | ndarray] = None)

Adds a set of measurements to the parent :class:~.Instrument`. The call adds N distinct measurements with N* distinct settings of *time*, *position* and *orientation*. For convenience, settings for one variable can be represented with one value and it will be automatically expanded to the number of measurements represented in the other variables, i.e. borrowing the idea of **broadcasting from numpy. Multiple measurement sets can be added to the Instrument

Parameters:

utc: Array, sequence or scalar of string, float, datetime or datetime64

The universal times of the set of measurements. It can be an array, sequence or scalar and each element should be a representation of universal time. If it is a scalar value then the same time value is assigned to every position given in observer_positions. All ali_elements of the array should be of the same type and should represent universal time.

roll_control: str

The technique used to specify the location of zero roll in the Geocentric Control Frame (ECEF) system. A description of values can be found in Roll Control.

platform_position: Tuple[str, sequence]

A two element tuple. The first element of the tuple is a string that specifies the positioning technique. The second element of the tuple is a sequence or array (or None) that contains parameter data for the selected technique. The array should be of size (Npts, NParam) where Npts is the number of points and Nparam is the number of parameters for the technique, e.g. (N,3), in the measurement set. The second element may be None if the technique is from_platform.

platform_orientation:

A three element tuple. The first element of the tuple is a string that specifies the orientation technique. The second element of the tuple is a sequence or array (or None) that contains parameter data for the selected technique. The array should be of size (Npts, NParam) where Npts is the number of points and Nparam is the number of parameters for the technique, e.g. (N,3), in the measurement set. The second element may be None if the technique is from_platform.

icf_orientation:

Optional. A two element tuuple. This option allows used to specify an array of instantaneous look vectors in the Instrument Control Frame (ICF). The first element of the tuple is a string that specifies the ref:icf look vector technique. The second element of the tuple is a sequence or array (or None) that contains parameter data for the selected technique. The array should be of size (Numlookvector, NParam) where Numlookvector is the number of instantaneous look vectors points and Nparam is the number of parameters for the look vector technique, e.g. (N,3),

clear()

Clears the current list of platform states inside the observation policy. This method should be called before starting a new observation policy

make_observation_set(platform: Platform)

Converts the internal list of measurements from previous calls to add_measurement_set into an an internally cached PositionAndOrientationArray. This method is normally called by the Platform class. The internal list of measurement sets has only been cached up to this point. This code goes through the measurements and generates all the necessary platform positions and rotation matrices using all the specified techniques.

Parameters:

platformPlatform

The Platform object that will be updated with the measurements defined in this object.

num_measurements() → int

Returns the number of samples in this observation policy

Returns:

int

The number of samples in the observation policy.

RotationMatrix

class RotationMatrix(array: List[List[float]] | ndarray = None)

A class that provides methods to calculate the rotation and transformation matrices used elsewhere in the package. These matrices are used to transform lines of sight and other vectors from one control frame to another.

• from_transform_to_destination_coordinates

• from_rotate_one_setofaxes_to_another

• from_yaw_pitch_roll

• from_ypr_in_first_frame_to_ypr_in_second_frame

• transform_vectors

Attributes:

R

RInv

Methods

IUnit()	Returns the identity matrix, \(\boldsymbol{IUnit}\) as a 3x3 matrix
from_azimuth_elevation_roll(azimuthradians, ...)	Create a rotation matrix that rotates a vector by the specified azimuth, elevation and roll.
from_rotate_one_setofaxes_to_another(A, B)	Generates the rotation matrix that rotates vectors specified in reference frame \(\boldsymbol{A}\) to vectors specified in reference frame \(\boldsymbol{B}\).
from_rotation_matrix(other)	Sets the rotation from another 3x3 matrix
from_transform_to_destination_coordinates(ax, ...)	Sets the rotation/transformation vector \(\boldsymbol{R}\) so it converts a vector, \(\vec{v}\), specified in the system, \(\boldsymbol{A}\) ( \(\hat{x}_a\) , \(\hat{y}_a\) , \(\hat{z}_a\) ), to the same vector but specified in the destination system, \(\boldsymbol{B}\) (\(\hat{x}_b\) , \(\hat{y}_b\) , \(\hat{z}_b\)).
from_yaw_pitch_roll(yaw, pitch, roll)	Creates a rotation matrix that applies yaw, pitch and roll in that order.
from_ypr_in_first_frame_to_ypr_in_second_frame(R1, RT)	Converts from a yaw-pitch-roll, rotation matrix provided in one coordinate frame (Frame 1) to the equivalent rotation matrix in another coordinate frame (Frame 2).
transform_vectors(lookvector)	Applies the internal rotation matrix to an array of N vectors.
yaw_pitch_roll()	Returns the current rotation matrix as the equivalent yaw, pitch roll (in radians).

static IUnit()

Returns the identity matrix, \(\boldsymbol{IUnit}\) as a 3x3 matrix

static from_azimuth_elevation_roll(azimuthradians: ndarray | float, elevationradians: ndarray | float, rollradians: ndarray | float) → RotationMatrix

Create a rotation matrix that rotates a vector by the specified azimuth, elevation and roll. It is is suitable for systems where the \(\hat{x}\) is horizontal and forwards, the \(\hat{z}\) axis is upwards and the \(\hat{y}\) points to the portside (left). In this system, azimuth is a left handed (clockwise, compass) rotation around \(\hat{z}\), elevation is a left handed rotation around \(\hat{y}\) (up is positive) and roll is a right-handed rotation around \(\hat{x}\) (leaning right is positive). The rotation matrix is created in the rotation order Azimuth, Elevation, Roll (rzyx)

Parameters:

azimuthradians

The azimuthual rotation in radians. The rotation is a left-handed rotation around the \(\hat{z}\) axis.

elevationradians

The vertical rotation in radians. The rotation is a left-handed rotation around the \(\hat{y}\) axis.

rollradians

The roll rotation in radians. The rotation is in a right haded sense around the \(\hat{x}\) axis

static from_rotate_one_setofaxes_to_another(A: ndarray, B: ndarray) → RotationMatrix

Generates the rotation matrix that rotates vectors specified in reference frame \(\boldsymbol{A}\) to vectors specified in reference frame \(\boldsymbol{B}\). IUnit.E. the 3 unit vectors of frame \(\boldsymbol{A}\) will be rotated on to the 3 unit vectors of frame \(\boldsymbol{B}\). The unit vectors for system \(\boldsymbol{A}\), \(\begin{bmatrix} \hat{x}_A & \hat{y}_A & \hat{z}_A \end{bmatrix}\) and system \(\boldsymbol{B}\), \(\begin{bmatrix} \hat{x}_B & \hat{y}_B & \hat{z}_B \end{bmatrix}\) are specified in a common system \(\begin{bmatrix} \hat{x'} & \hat{y'} & \hat{z'} \end{bmatrix}\) as 3x3 matrices.

\[\begin{split}A= \begin{pmatrix} \hat{x}_{A}.\hat{x}' & \hat{y}_{A}.\hat{x}' & \hat{z}_{A}.\hat{x}' \\ \hat{x}_{A}.\hat{y}' & \hat{y}_{A}.\hat{y}' & \hat{z}_{A}.\hat{y}' \\ \hat{x}_{A}.\hat{z}' & \hat{y}_{A}.\hat{z}' & \hat{z}_{A}.\hat{z}' \\ \end{pmatrix}\end{split}\]

\[\begin{split}B = \begin{pmatrix} \hat{x}_{B}.\hat{x}' & \hat{y}_{B}.\hat{x}' & \hat{z}_{B}.\hat{x}' \\ \hat{x}_{B}.\hat{y}' & \hat{y}_{B}.\hat{y}' & \hat{z}_{B}.\hat{y}' \\ \hat{x}_{B}.\hat{z}' & \hat{y}_{B}.\hat{z}' & \hat{z}_{B}.\hat{z}' \\ \end{pmatrix}\end{split}\]

The rotation matrix \(\boldsymbol{R}\) is the operation that transforms the three unit vectors of \(\boldsymbol{A}\) in to the three unit vectors of \(\boldsymbol{B}\)

\[\begin{split}\boldsymbol{RA} &= \boldsymbol{B}\\ \boldsymbol{R} &= \boldsymbol{BA^{-1}}\\\end{split}\]

Parameters:

A

A 3x3 matrix with the 3 unit vectors of control frame \(\boldsymbol{A}\) \(\begin{bmatrix} \hat{x}_A & \hat{y}_A & \hat{z}_A \end{bmatrix}\) expressed in a common coordinate sytem, \(\hat{x}'\), \(\hat{y}'\), \(\hat{z}'\).

B

A 3x3 matrix with the 3 unit vectors of control frame \(\boldsymbol{B}\) \(\begin{bmatrix} \hat{x}_B & \hat{y}_B & \hat{z}_B \end{bmatrix}\) expressed in a common coordinate sytem, \(\hat{x}'\), \(\hat{y}'\), \(\hat{z}'\).

Examples:

Rotate Platform and Instrument to look at point on Earth

A typical usage example is to calculate the rotation matrix for a platform so an instrument on that platform will look at a point on the Earth. The solution is to align the platform control frame with the local geodetic system (west, south, up) and then express the instrument control frame, \(\boldsymbol{A}\) , as geographic geocentric unit vectors via the west,south, up unit vectors. The \(\boldsymbol{B}\) unit vectors are taken as the look unit vector from the platform to the desired point on Earth, \(\hat{x}_B\), while \(\hat{y}_B\) and \(\hat{z}_B\) are chosen to meet observation requirements, eg horizontal slit etc. In this example both \(\boldsymbol{A}\) and \(\boldsymbol{B}\) can be readily expressed in geographic geocentric coordinates using other parts of the software package.

Rotate Instrument Control Frame to Platform Control Frame

For this example we want to rotate vectors specified in the instrument control frame so they are specified in the platform control frame. For example the CATS instrument was located on the backside of the gondola during the 2018 campaign and required the line of sight to be rotated so it looked backwards. The solution is specify the instrument control frame unit vectors in platform control frame coordinates and recognise that the common coordinates are the platform control frame unit vectors. In this case the instrument control frame is system \(\boldsymbol{A}\) and the platform control frame is system \(\boldsymbol{B}\). Because system \(\boldsymbol{B}\) is the common system then matrix \(\boldsymbol{B }\) is simply the unit vector \(\boldsymbol{IUnit}\). Matrix \(\boldsymbol{A}\) must be calculated from instrument and platform configuration details but then \(\boldsymbol{R}\) is readily derived.

from_rotation_matrix(other: ndarray)

Sets the rotation from another 3x3 matrix

static from_transform_to_destination_coordinates(ax: ndarray, ay: ndarray, az: ndarray)

Sets the rotation/transformation vector \(\boldsymbol{R}\) so it converts a vector, \(\vec{v}\), specified in the system, \(\boldsymbol{A}\) ( \(\hat{x}_a\) , \(\hat{y}_a\) , \(\hat{z}_a\) ), to the same vector but specified in the destination system, \(\boldsymbol{B}\) (\(\hat{x}_b\) , \(\hat{y}_b\) , \(\hat{z}_b\)). This is implemented as a dot product.

\[\begin{split}\begin{split} \vec{V}_A &= a_x\hat{x}_a + a_y\hat{y}_a + a_z\hat{z}_a \\ \vec{V}_B &= b_x\hat{x}_b + b_y\hat{y}_b + b_z\hat{z}_b \\ \end{split}\end{split}\]

where

\[\begin{split}\begin{split} \hat{x}_a &=& a_{11}\hat{x}_b +& a_{12}\hat{y}_b +& a_{13}\hat{z}_{b} \\ \hat{y}_a &=& a_{21}\hat{x}_b +& a_{22}\hat{y}_b +& a_{23}\hat{z}_{b} \\ \hat{z}_a &=& a_{31}\hat{x}_b +& a_{32}\hat{y}_b +& a_{33}\hat{z}_{b} \\ \end{split}\end{split}\]

then

\[\begin{split}\begin{pmatrix} Bx \\ By \\ Bz \\ \end{pmatrix} = \begin{pmatrix} a_{11} & a_{21} & a_{31} \\ a_{12} & a_{22} & a_{32} \\ a_{13} & a_{23} & a_{33} \\ \end{pmatrix} \begin{pmatrix} Ax \\ Ay \\ Az \\ \end{pmatrix}\end{split}\]

Note that the 3x3 matrix is the transpose of the unit vector equations

Parameters:

ax

A 3 element array expressing the \(\hat{ax}\) unit vector of frame \(\boldsymbol{A}\) in terms of the unit vectors in \(\boldsymbol{B}\)

ay

A 3 element array expressing the \(\hat{ay}\) unit vector of frame \(\boldsymbol{A}\) in terms of the unit vectors in \(\boldsymbol{B}\)

az

A 3 element array expressing the \(\hat{az}\) unit vector of frame \(\boldsymbol{A}\) in terms of the unit vectors in \(\boldsymbol{B}\).

static from_yaw_pitch_roll(yaw: ndarray | float, pitch: ndarray | float, roll: ndarray | float) → RotationMatrix

Creates a rotation matrix that applies yaw, pitch and roll in that order. This method is intended for aircraft system where \(\hat{x}\) is looking forward looking, \(\hat{z}\) is downwards and \({y}\) is towards starboard. All angles are made in a right-handed sense around the axis of rotation. Typically, positive pitch is turning “upwards”, positive yaw is “turning towards the right” and positive roll is “leaning to the right”.

The matrix is created in the rotation order Yaw, Pitch, Roll (rzyx). The rotations are intrinsic, meaning the axes of rotations are also rotated. Intrinsic rotations require the rotations to be applied in reverse order (ie roll, pitch, yaw) but then the matrix operations are applied from right to left so we get the order yaw, @ pitch @ roll in the actual code to represent (yaw, pitch, roll).

Parameters:

yaw

The yaw angle in radians. This rotation is applied first to the z axis.

pitch

The pitch angle in radians. This rotation is applied second to the rotated y axis.

roll

The roll angle in radians. This rotation is applied last to the rotated x axis.

static from_ypr_in_first_frame_to_ypr_in_second_frame(R1: RotationMatrix, RT: RotationMatrix) → RotationMatrix

Converts from a yaw-pitch-roll, rotation matrix provided in one coordinate frame (Frame 1) to the equivalent rotation matrix in another coordinate frame (Frame 2). Returns the converted rotation matrix, \(R_2\), which should be used in the second coordinate frame. to apply the yaw-pitch-roll measured in the first frame

This code was initially developed to convert and compare yaw, pitch roll measured on one IMU to yaw pitch and roll measured on another, rotated, IMU. It was applied to map the CNES IMU attitude solution to the iFTS IMU which was on the same gondola but at a rotated angle (nominally 90 degres). It was used to replace the iFTS IMU attitude solution which was at too coarse a resolution.

Theory

We use the rotation matrix defined for the first coordinate frame, \(R_1\), to map a vector, \(u_i\), specified in frame 1 coordinates to a geographic vector, \(w_{geo}\),

\[w_{geo} = R_1 u_i\]

We wish to find the equivalent rotation matrix for frame 2, \(R_2\) that maps the same vector but specified in frame 2, \(v_i\), to the same geographic vector, \(w_{geo}\). The vectors \(u_i\) and \(v_i\) are related via the rotation matrix transform from frame 2 to frame 1, \(R_T\). We wish to keep the vector given in frame 2, \(v_i\), constant and obtain its coordinates as expressed in frame 1. This is given using the inverse of the transform rotation matrix:

\[u_i = R_T^{-1} v_i\]

thus we can substitute for \(u_i\) in the above to get,

\[w_{geo} = R_1 R_T^{-1} v_i\]

Quite generally, the required rotation matrix in the second coordinate frame, \(R2\) is the one that maps the instrument control frame to the platform vector, it satisfies the equation,

\[w_{geo} = R_2 v_i\]

Therefore, by inspection we can see the required rotation matrix in the second frame, \(R_2\), is given by:

\[R_2 = R_1 R_T^{-1}\]

Parameters:

R1:

The rotation matrix in the first coordinate system, \(R_1\), For example, this may be derived from the yaw, pitch roll measured on by the first IMU system.

RT:

The rotation matrix that rotates from the second coordinate system to the first coordinate system, \(R_T\).

Returns:

RotationMatrix

The rotation matrix, \(R2\), in the second coordinate frame.

transform_vectors(lookvector: ndarray) → ndarray

Applies the internal rotation matrix to an array of N vectors. The incoming array must of the form (3,N) where the first dimension contains the X,Y,Z components of the N vectors.

Parameters:

lookvector:

An array (3,N) of incoming vectors that will be rotated/transformed. The first dimension contains the X,Y,Z components of the N vectors

Returns:

An array of size (3,N) which is the set of vectors generated by applying the rotation matrix to the incoming vectors. The first dimension contains the X,Y,Z components of the rotated N vectors

yaw_pitch_roll() → Tuple[float, float, float]

Returns the current rotation matrix as the equivalent yaw, pitch roll (in radians). For example, see https://lavalle.pl/planning/node103.html

Returns:

A three element tuple of [yaw, pitch roll], all expressed in radians.

UnitVectors

class UnitVectors(vectors: List[List[float]] | Tuple[ndarray, ndarray, ndarray] | ndarray = None)

A class to hold the unit vectors \(\begin{bmatrix} \hat{x} & \hat{y} & \hat{z} \end{bmatrix}\) for one reference frame specified in terms of another reference frame, \(\begin{bmatrix} \hat{x}' & \hat{y}' & \hat{z}' \end{bmatrix}\) The components of each unit vector occupy a column of the matrix.

\[\begin{split}\begin{pmatrix} \hat{x}.\hat{x}' & \hat{y}.\hat{x}' & \hat{z}.\hat{x}' \\ \hat{x}.\hat{y}' & \hat{y}.\hat{y}' & \hat{z}.\hat{y}' \\ \hat{x}.\hat{z}' & \hat{y}.\hat{z}' & \hat{z}.\hat{z}' \\ \end{pmatrix}\end{split}\]

Note that the components of \(\begin{bmatrix} \hat{x}' & \hat{y}' & \hat{z}' \end{bmatrix}\) in terms of \(\begin{bmatrix} \hat{x} & \hat{y} & \hat{z} \end{bmatrix}\) is the transpose (which is also the inverse) of this matrix.

Attributes:

R

Methods

X
Y
Z