Internal Classes¶

ObservationPolicy¶

class skretrieval.platforms.platform.ObservationPolicy¶

Implements the Observation Policy object for the Platform. This object stores a list of platform states. Any observation policy breaks down into an array of samples where the platform position, orientation and time are specified for each sample.

The end user will often want call the following methods:

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 ObservationPolicy as one of its inputs to the radiative transfer engine. The user must add at least one platform state to the ObservationPolicy 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.

add_current_state(platform_attitude: skretrieval.platforms.platform.platform_pointing.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: The number of samples in the observation policy.
Return type: int

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: 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.
Return type: np.ndarray( 3,Nt)

icf_to_ecef_rotation_matrix()¶

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

Returns: 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
Return type: List[RotationMatrix]

numsamples_in_observationset() → int¶

Returns the number of samples in this observation policy

Returns: The number of samples in the observation policy.
Return type: int

to_optical_geometry() → List[skretrieval.core.OpticalGeometry]¶

Converts the platform orientations defined in thos ObservationPolicy 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: The list of measurement definitions used by retrieval code.
Return type: List[OpticalGeometry]

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 skretrieval.platforms.platform.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.

convert_gcf_to_ecef(v: numpy.ndarray) → numpy.ndarray¶

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

Parameters

v (np.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

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.

Return type

np.ndarray

convert_icf_to_ecef(v: numpy.ndarray) → numpy.ndarray¶

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

Parameters

v (np.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

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.

Return type

np.ndarray

convert_icf_to_gcf(v: numpy.ndarray) → numpy.ndarray¶

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

Parameters

v (np.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

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.

Return type

np.ndarray

force_pcf_rotation_matrix(GEO: skretrieval.platforms.platform.rotationmatrix.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 (_IRM) 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: GEO (UnitVectors) – 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() → skretrieval.platforms.platform.rotationmatrix.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: 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}}\)
Return type: np.ndarray

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: float, elevation_degrees: float, roll_degrees: 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 Platform Control Frame (PCF). Note that we try to use the aircraft definitions of azimuth, elevation and roll and we apply the three 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 starboard (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_degrees (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_degrees (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_degrees (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: float, pitch_degrees: float, roll_degrees: 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_degrees (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_degrees (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_degrees (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.

rotate_instrument_in_icf(azimuth_degrees: float, elevation_degrees: float, roll_degrees: 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_degrees (float) – The azimuth of the instrument boresight in the platform control frame in degrees. Azimuth is left handed rotation around \(\hat{z}_{ICF}\).
elevation_degrees (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_degrees (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: Optional[Tuple[float, float, float, numpy.datetime64]] = None, latlonheightandt: Optional[Tuple[float, float, float, numpy.datetime64]] = None)¶

Sets the location of the platform to the specified location.

Parameters

xyzt (Tuple[float, float, float, np.datetime64]) – Set the platform location using geographic geocentric coordinates
latlonheight (Tuple[float, float, float]) – The the platform location using geodetic corodinates. The tuple is a 4 element array, [0] is latitue, [1] is longitude [2] is height in meters, [3] is platform_utc as float representing MJD or numpy.datetime64

PlatformLocation¶

class skretrieval.platforms.platform.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,

update_position().

position

In addition, platforms that move can override,

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.

earth_location

lat_lon_height.

property earth_location¶

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

Returns: EarthLocation
Return type: Location of the platform as an astropy EarthLocation object.

property 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. This is a convenience function wrapped around position

Returns: A 3 element array of [ latitude, longitude, height in meters]
Return type: numpy.ndarray, Array[3,]

abstract property position¶

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: A three element array storing the X,Y,Z geocentric location (ITRF ecef, wgs84) of the platform. All numbers are in meters.
Return type: np.ndarray(3,)

abstract update_orientation(utc: Union[datetime.datetime, numpy.datetime64]) → Optional[Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]]¶

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

Parameters: utc (datetime) – The time at which to update the location of the platform
Returns: Tuple[ x – 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.
Return type: np.ndarray(3,), y:np.ndarray(3,), z:np.ndarray(3,) ]

abstract update_position(utc: Union[datetime.datetime, numpy.datetime64]) → Optional[numpy.ndarray]¶

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: utc (datetime) – The time at which to update the location of the platform
Returns: The three element X,Y,Z geographic geocentric location of the platform
Return type: np.ndarray, Array[3]

abstract update_velocity(utc: Union[datetime.datetime, numpy.datetime64]) → Optional[numpy.ndarray]¶

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: utc (datetime) – The time at which to update the location of the platform
Returns: The three element X,Y,Z geographic geocentric location of the platform
Return type: np.ndarray, Array[3]

abstract property velocity¶

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: The three element X,Y,Z geographic geocentric velocity of the platform. All numbers are in meters/second.
Return type: np.ndarray, Array[3,]

OrientationTechniques¶

class skretrieval.platforms.orientation_techniques.OrientationTechniques¶

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

add_measurement_set(utc: Union[float, str, numpy.datetime64, datetime.datetime, numpy.ndarray, Sequence[Union[float, str, numpy.datetime64, datetime.datetime, numpy.ndarray]]], observer_positions: Tuple[str, Union[Sequence, numpy.ndarray]], look_vectors: Tuple[str, str, Union[Sequence, numpy.ndarray]], instrument_internal_rotation: Optional[Union[Sequence, numpy.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 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.
observer_positions (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.
look_vectors – 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.
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()¶: 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 ObservationPolicy. 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: platform (Platform) – 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: The number of samples in the observation policy.
Return type: int