This is the documentation for the skplatform package

Platform#

class Platform(observation_policy: Optional[PositionAndOrientationArray] = None, platform_locator: Optional[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,

Optional. Specify how an instrument is mounted on the platform. This defines the Instrument Control Frame (ICF).
Specify the universal times for a set of measurements
Specify the position of the platform for a set of measurements using a variety of positioning techniques, see Positioning Technique and add_measurement_set
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.
The orientations define the Platform Control Frame (PCF) and the positions define the Geodetic Control Frame (GCF).
Create the internal PositionAndOrientationArray for the measurement set, see make_observation_policy.
Convert the PositionAndOrientationArray to arrays of position and instrument look vectors suitable for retrieval code.

__init__(observation_policy: Optional[PositionAndOrientationArray] = None, platform_locator: Optional[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: The number of samples in the current observation policy
Return type: int

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 Platform 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 sktime 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 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_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)

property icf_to_ecef_rotation_matrices: List[RotationMatrix]#

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

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

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: The number of samples in the current observation set
Return type: int

property observation_policy: PositionAndOrientationArray#

Returns the current internal PositionAndOrientationArray object.

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

property platform_ecef_positions: ndarray#

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)

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.

Satellite Classes#

Satellite classes are used to locate the position of a platform for a variety of orbits. They are derived from class PlatformLocation which allows them to be used as platform locators in class Platform when coupled with the from_platform positioning technique.

Example:

from skplatform import Platform

def make_geometry():
    kepler = SatelliteKepler('2020-09-24T12:00:00.000000', period_from_altitude = 600000.0, inclination_radians= radians(97.0), longitude_of_ascending_node_degrees = 82.0, eccentricity= 0.05)
    platform = Platform(platform_locator=kepler)
    utc  = ['2020-09-24T12:15:36.123456', '2020-09-24T12:15:37.456123', '2020-09-24T12:15:38.654321', '2020-09-24T12:15:39.654321']
    pointing_values = [(35000, 10, 0), (27000, 5, 0), (24000, 0, 0), (21000, -5, 0)]
    platform.add_measurement_set(utc, ('from_platform',), ('tangent_altitude', 'limb', pointing_values))

The satellite classes can also be used as stand-alone classes in which case the user would execute the following steps.

Create a specific instance of a satellite.
Update the satellite position to a given instant in time, see update_position
Get the satellite position using one of the available methods, see position, earth_location or lat_lon_height
Repeat steps 2 and 3.

for example:

dt = timedelta(minutes=1.0)                                         # step time of our simulation is one minute
numtimes = 1440                                                     # Simulate for 1 day = 1440 * one minute
platform_utc = datetime(2019,7,26, hour =20, minute=15, second=00)  # start time of our simulation
sat = SatelliteSunSync(platform_utc,                                # Create the satellite
                       orbittype='sgp4',
                       period_from_altitude=600000.0,
                       localtime_of_ascending_node_hours=18.25)

answers = np.zeros([3, numtimes])                                   # make an array to hold the latitude, longitude, altitude of each satellite at each simulation step
times = np.zeros([numtimes], dtype='datetime64[us]')                # make an array to hold the UTC time of each simulation step.
for i in range(numtimes):                                           # for each time step
    tnow = platform_utc + i * dt                                    # get the next time step
    times[i] = tnow                                                 # save the time of the step
    sat.update_position(tnow)                                       # Update the satellite position
    answers[:, i] = sat.lat_long_height                             # convert XYZ position and save

Users should be aware the satellite classes may internally implement numerical integration using Runge-Kutta algorithms and should avoid large time steps (e.g. multiple orbits) as this may result in long execution times in the best case and inaccuracy in the worst case.

Internal Classes#

Internal Classes