Platform¶

The Platform class is a top level class describing the platform used in the simulation or retrieval. The class is builds on base class PlatformPointing and has an ObservationPolicy object. The class provides a selection of methods to set the position, orientation and time of the platform. Quick links to some of the more useful methods are below,

Platform and Instrument Orientation methods
- orient_instrument_on_platform()
- orient_platform_in_space()
Instrument Boresight Pointing methods
- set_boresight_to_look_at_geodetic_location()
- set_boresight_to_look_at_tangent_altitude_and_azimuth()
- set_boresight_to_look_at_geocentric_location()
Platform Location methods
Pointing Rotation Matrices

class skimpy.Platform(observation_policy: skimpy.platform.observationpolicy.ObservationPolicy = None)¶

__init__(observation_policy: skimpy.platform.observationpolicy.ObservationPolicy = None)¶

Creates a new platform object.

Parameters:	observation_policy (ObservationPolicy) – Default None. This optional parameter can use an existing ObservationPolicy object rather than create a new empty instance.

add_current_platform_state() → int¶

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

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

add_positions_and_geodetic_points(pos_x: numpy.ndarray, pos_y: numpy.ndarray, pos_z: numpy.ndarray, look_at_latitudes: numpy.ndarray, look_at_longitudes: numpy.ndarray, look_at_altitudes: numpy.ndarray, utc: numpy.ndarray, clear_states: bool = True)¶

Adds a list of platform positions and look vectors to the internal list of states. The look vector of the platform is configured at each position to look at the specified geodetic location.

Parameters:

pos_x (np.ndarray(N)) – An array of N points, one point for each RT calculation. Stores the X component of the geographic geocentric location of the platform in meters
pos_y (np.narray(N)) – An array of N points. Stores the Y component of the geographic geocentric location of the platform in meters
pos_z (np.ndarray(N)) – An array of N points. Stores the X component of the geographic geocentric location of the platform in meters
look_at_latitudes (np.ndarray(N)) – An array of N points. Stores the latitude in degrees of the location the platform will look towards
look_at_longitudes (np.ndarray(N)) – An array of N points. Stores the longitude in degrees of the location the platform will look towards
look_at_altitudes (np.ndarray(N)) – An array of N points. Stores the altitude in meters of the location the platform will look towards
utc (np.ndarray(N)) – The coordinated universal time of each RT calculation
clear_states (bool) – Optional, default True. If true then clear the current observation set before adding these new lines of sights.

add_tangent_heights(tangent_altitudes_meters: numpy.ndarray, geographic_bearing_degrees: float, clear_states: bool = True)¶

Sets the platform to look at an array of tangent altitudes at a given geographic bearing from the platforms position.

Parameters:

tangent_altitudes_meters (np.ndarray(N)) – An array of N tangent altitudes in meters. The tangent altitudes must be below the platform’s current position. One line of sight sample is added to the observation set for each tangent altitude.
geographic_bearing_degrees (float) – The geographic bearing of the desired tangent points from the current platform position. N=0, E=90, S=180, W=270
clear_states (bool) – Optional, default True. If true then clear the current observation set before adding these new lines of sights.

lines_of_sight_from_icf_vectors(los_icf: numpy.ndarray) → numpy.ndarray¶

Returns the lines of sight in geographic geocentric coordinates for the given spectral_window for each times in the current observation policy.

Parameters:	los_icf (np.ndarray( 3,Nlos)) – A 2-D array of N unit vectors expressed in the instrument control frame
Returns:	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.
Return type:	np.ndarray (3,Nlos, Ntime)

lines_of_sight_from_window(window: skimpy.instrument.spectralwindow.SpectralWindow, high_res_los=False) → numpy.ndarray¶

Returns the lines of sight in geographic geocentric coordinates for the given spectral_window for al the times in the observation set. The lines of sight are taken from the spectral_window’s field of view and can either be the central line of sight or the high resolution lines of sight that span the field of view.

Parameters:	window (SpectralWindow) – The spectral_window that will provide the lines of sight in the instrument control frame. The spectral_window can provide either an array of lines of sight in the instrument control frame that sub-divide the spectral_window’s field of view or a single central line of sight. high_res_los (bool) – If True then get the high resolution lines of sight that span the of the high resolution are used. Otherwise the central line of sight is used.. This option controls the dimensional size of teh returned array. If True then the returned array has 3 dimensions
Returns:	A numpy array is returned with the 3 element unit vectors of the lines of sight expressed in geographic geocentric coordinates. If option high_res_los is False then the array is two dimensional (3, Nt) with one unit vector for each time in the observation set. If high_res_los is True than the returned array is three dimensional (3, NLos, Nt): one unit vector for each line of sight across the field of view and each time in the observation set.
Return type:	np.ndarray (3,Ntime) or (3,Nlos, Ntime)

numsamples¶

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

Returns:	The nimber of samples in the current observation set
Return type:	int

observation_policy() → skimpy.platform.observationpolicy.ObservationPolicy¶

Returns the current internal ObservationPolicy object.

Returns:	Returns the current internal ObservationPolicy object.
Return type:	ObservationPolicy

orient_instrument_on_platform(azimuth_degrees: float, elevation_degrees: float, roll_degrees: float = 0.0)¶: see PlatformPointing.orient_instrument_on_platform() for a complete description

orient_platform_in_space(yaw_degrees: float, pitch_degrees: float, roll_degrees: float)¶: see PlatformPointing.orient_platform_in_space() for a complete description

platform_rotation_matrices¶

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

Returns:	The X,Y,Z platform_rotation_matrices of the platform.
Return type:	np.ndarray(3,N)

positions¶

Returns the position of the platform for each RT calculation

Returns:	The X,Y,Z location of the platform for each RT calculation. The coordinates are in meters form the center of the Earth,
Return type:	np.ndarray(3,N)

set_boresight_from_limb_looking_vector(lookvector: numpy.ndarray)¶: see PlatformPointing.set_boresight_from_limb_looking_vector() for a complete description

set_boresight_to_look_at_geocentric_location(targetlocation: numpy.ndarray, nadir_azimuth_of_inst_z: float = 180.0)¶: see PlatformPointing.set_boresight_to_look_at_geocentric_location() for a complete description

set_boresight_to_look_at_geodetic_location(target_latitude: float, target_longitude: float, target_height_meters: float, **kwargs)¶: see PlatformPointing.set_boresight_to_look_at_geodetic_location() for a complete description

set_boresight_to_look_at_tangent_altitude(target_tangent_altitude: float, target_geographic_bearing: float)¶: see PlatformPointing.set_boresight_to_look_at_tangent_altitude() for a complete description

set_nadir_mode(isnadir: bool)¶: see PlatformPointing.set_nadir_mode() for a complete description

set_platform_location(**kwargs)¶: see PlatformPointing.set_platform_location() for a complete description

utc¶

Returns the UTC of each RT calculation in the observation set

Returns:	The UTC of each RT calculation. Returns an array of datetime64
Return type:	np.ndarray(N)

Platform_Pointing¶

class skimpy.platform.platform_pointing.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_geo(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}_{GEO}\) component, v[1,:] is the \(\hat{y}_{GEO}\) component, v[2,:] is the \(\hat{z}_{GEO}\) 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

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

Converts vectors expressed in the instrument coordinate frame to geographic geocentric 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}_{GEO}\) component, v[1,:] is the \(\hat{y}_{GEO}\) component, v[2,:] is the \(\hat{z}_{GEO}\) component.
Return type:	np.ndarray

get_icf_to_geo_matrix() → skimpy.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 GEO geocentric control frame. The matrix should be applied as \(\boldsymbol{V_{GEO}} = \boldsymbol{R} @ \boldsymbol{V_{ICF}}\)
Return type:	np.ndarray

instrument_rotation_matrix() → skimpy.platform.rotationmatrix.RotationMatrix¶

Returns the rotation matrix that orients the instrument on the platform. This specifies the orientation of the instrument in the platform control frame

Returns:	Rotation matrix that orients the instrument on the platform.
Return type:	RotationMatrix

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

orient_instrument_on_platform(azimuth_degrees: float, elevation_degrees: float, roll_degrees: float = 0.0)¶

Orients an instrument on a platform by setting up the azimuth, elevation and roll of the instrument with respect to the platform control frame. The instrument control frame is initally configured so azimuth and elevation are sensible, see Instrument Control Frame (ICF), where the following transformation is internally applied,

\(\hat{x}_{ICF} = +\hat{x}_{PCF}\)
\(\hat{y}_{ICF} = -\hat{y}_{PCF}\)
\(\hat{z}_{ICF} = -\hat{z}_{PCF}\)

If azimuth, elavation and roll are all set to zero then the instrument boresight will point along \(\hat{x}_{PCF}\) and the instrument’s vertical direction will point upwards.

Parameters:

azimuth_degrees (float) – The azimuth of the instrument boresight in the platform control frame in degrees.
elevation_degrees (float) – The elevation of the instrument boresight in the platform control frame in degrees.
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), where,

\(\hat{x}_{PCF}\) pointing due north
\(\hat{y}_{PCF}\) pointing due East.
\(\hat{z}_{PCF}\) pointing down.

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.

platform_rotation_matrix() → skimpy.platform.rotationmatrix.RotationMatrix¶

Return the rotation matrix that orients the platform in local geodetic space.

Returns:	The rotation matrix that orients the platform in local geodetic space.
Return type:	RotationMatrix

set_boresight_from_limb_looking_vector(lookvector: numpy.ndarray)¶

Sets the platform rotation matrices so the boresight of the instrument is looking in direction lookvector. In limb mode the instruments Z axis is aligned with the local vertical

Parameters:	vector (look) – A three element look vector, looking from the platform towards the limb

set_boresight_to_look_at_geocentric_location(targetlocation: numpy.ndarray, nadir_azimuth_of_inst_z: float = 180.0)¶

Sets the rotation matrix of the platyform so the boresight of the instrument will look at the given target location. The instrument’s the primary boresight is will look at the geocentric location.

The roll of the instrument around the look vector is trickier. For non-nadir sitiuations the instrument Z axis, which is typically “up”, is aligned so it is as parallel to “local up” at the target location as possible. This is sensible for limb viewing instruments as the instrument Z axis needs to be up at the target point and the instrument Y axis nees to be horizontal.

The roll around the look vector is trickier for nadir observations as the instrument boresight and local up are (almost) anti-parallel implying the instrument Z axis is perpendicular to local up breaking the assumptions made in non-nadir mode. If nadir observations are established then the instrument Z axis is rolled aound the look vector until is as parallel as possible to a horizontal azimuthal unit vector at the target location. The azimuth of the horizontal unit vector is specified by parameter nadir_azimuth_of_inst_z, the default azimuth is due South (180) where N=0, E=90, S=180 and W=270.

The system decides if it has a nadir or non-nadir situation by looking at the angle bewteen the look vector and the local up at the target location. If the angle is smaller than or equal to nadir_threshold_angle then it is assumed to be a nadir observation. If the angle is greater than this angle it is a non-nadir situation.

It is possible to force the system into nadir based calculations by setting nadir_threhold_angle to 180.0. In this case the Z axis is always aligned with the specified azimuth. However it is the callers responsibility to ensure that the look vector is not exactly parallel to the horizontal unit vector at azimuth nadir_azimuth_of_inst_z. This is guaranteed for nadir like scenarios but may be violated if you force a limb viewing geometry to be treated as nadir-like. The default function parameters provide a non-nadir setting for all angles apart from true nadir situations.

Parameters:	targetlocation (np.ndarray) – The 3 element geocentric location [X,Y,Z] of the desired target location. nadir_azimuth_of_inst_z (float) – If nadir mode is enabled then \(\hat{z}_{ICF}\) is rotated around the look vector so it is as parallel as it can be to the horizontal unit vector at this geographic azimuth at the target location.

set_boresight_to_look_at_geodetic_location(target_latitude: float, target_longitude: float, target_height_meters: float, **kwargs)¶

Sets rotation matrix of the system so the boresight of the instrument points at the target located at the specified latitude, longitude and height. This is a wrapper for method set_boresight_to_look_at_geocentric_location().

Parameters:	target_latitude (float) – The geodetic laltitude of the target location. target_longitude (float) – The geodetic longitude of the target location. target_height_meters (float) – The geodetic altitude of the target location in meters *kwargs (Dict{str,Any*]) – The keyword arguments supported by `set_boresight_to_look_at_geocentric_location()`

set_boresight_to_look_at_tangent_altitude(target_tangent_altitude: float, target_geographic_bearing: float)¶

Sets the rotation matrix of the system so the boresight of the instrument is looking at a tangent point below the platform at the given observers geographic bearing (N = 0, E = 90, S = 180, W = 270).

Parameters:	target_tangent_altitude (float) – The tangent altitude of the target location. The tangent altitude must be less than the current height of the platform. An exception is raised if it is not. target_geographic_bearing (float) – The geographic bearing of the tangent altitude from the current platform location

set_nadir_mode(isnadir: bool)¶

Sets the platform pointing to use nadir mode. This controls how the insrument Z unit vector is aligned. In nadir mode the user specifies the geographic azimuth of the Z vector. If we are not in nadir mode the Z unit vector is aligned with local up (at the limb point)

Parameters:	isnadir (bool) – sets nadir mode if True, else clears nadir mode.

set_platform_location(xyzt: Tuple[float, float, float, numpy.datetime64] = None, latlonheightandt: 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 utc as float representing MJD or numpy.datetime64