Scene model (ryscene)

The module provides scene-related models and information.

Overview

Scene orientation locus modelling using quaternion SLERP interpolation.

Provides the Scene class for reading a time-stamped 6-DOF sensor locus from a CSV file, converting Euler angles to quaternions (via the transformations library by Christoph Gohlke), and spherical-linear (SLERP) interpolating orientation between time steps.

The transformations library follows the “column vectors on the right” and “row major storage” (C contiguous) conventions. Angles are in radians unless stated otherwise. Quaternions w+ix+jy+kz are represented as [w, x, y, z].

Euler angle sequence used throughout: yaw (z), pitch (y), roll (x) – encoded as 'rzyx' in the transformations API. Do not change this sequence without updating Scene.sequence and all callers.

See the __main__ block for a worked usage example.

This package was partly developed to provide additional material in support of students and readers of Electro-Optical System Analysis and Design: A Radiometry Perspective, C. J. Willers, ISBN 9780819495693, SPIE Monograph PM236, SPIE Press, 2013. http://spie.org/x648.html?product_id=2021423

Module classes

class Scene

Bases: object

Model a sensor’s 6-DOF orientation locus and interpolate between poses.

Reads a time-stamped position and orientation CSV file, converts Euler angles to quaternions, and provides SLERP-based interpolation so that the sensor orientation can be queried at arbitrary times.

Coordinate system: Right-Hand, North (x), East (y), Down (z).

• Yaw / Azimuth – positive from x to y; clockwise when viewed along +z.

• Roll – positive from y to z; clockwise when viewed along +x.

• Pitch / Elevation – positive from z to x; clockwise when viewed along +y.

The Euler sequence used to map camera axes into the world frame is yaw (z) -> pitch (y) -> roll (x), encoded as 'rzyx'.

dfLocus

pandas.DataFrame loaded by readLocus(), or None before the first call.

sequence

Euler-angle sequence string used by the transformations library (always 'rzyx').

readLocus(filename)

Read a locus CSV file and compute derived angle and quaternion columns.

The CSV must have no spaces and use the following column layout (time in seconds, x/y/z in metres, angles in degrees):

time,x,y,z,yawDeg,pitchDeg,rollDeg
0,0,0,0,0,0,0
1,0,0,0,30,0,0
2,0,0,0,30,15,0
3,0,0,0,30,15,20
4,0,0,0,0,0,0

After loading, the DataFrame gains four extra columns:

• yawRad, pitchRad, rollRad – angles converted to radians.

• sequence – the Euler sequence string ('rzyx') on every row.

• quat – a list containing the (4,) quaternion array for that row.

Parameters:

filename – Path to the locus CSV file.

interpLocus(ltime)

Interpolate the sensor orientation at an arbitrary time using SLERP.

Finds the two locus rows that bracket ltime, computes the parametric fraction t between them, and spherically interpolates the quaternions.

Parameters:

ltime – Query time in seconds. Must lie strictly between the first and last times recorded in dfLocus.

Returns:

A 4-tuple (yaw, pitch, roll, q) where yaw, pitch, and roll are the interpolated Euler angles in radians and q is the interpolated (4,) quaternion array.

Module functions

df_euler2quat(row)

Convert a DataFrame row’s Euler angles to a quaternion.

Intended to be called via DataFrame.apply(df_euler2quat, axis=1). The result is wrapped in a list so that pandas stores the entire quaternion array as a single cell value rather than expanding it into separate columns.

Parameters:

row – A pandas.Series with at minimum the keys 'yawRad', 'pitchRad', 'rollRad', and 'sequence'.

Returns:

A one-element list whose sole item is a (4,) numpy array [w, x, y, z] representing the quaternion. The list wrapper is required by pandas – do not remove it.

unitxrotate(sc)

Rotate a unit vector along the x-axis through each locus pose.

Prints the rotation quaternion and rotated point for every row in sc.dfLocus. This is a diagnostic/visualisation helper; it is not part of the public API.

Parameters:

sc – A Scene instance with dfLocus loaded.

applyInterpLocus(sc, t)

Interpolate the locus at time t and return a labelled Series.

Intended to be used with DataFrame.apply when the time column is passed as the argument, with sc bound via a lambda or partial:

dfi['result'] = dfi['time'].apply(lambda t: applyInterpLocus(sc, t))

Parameters:

• sc – A Scene instance with dfLocus loaded.

• t – Query time in seconds.

Returns:

A pandas.Series with keys 'yaw', 'pit', 'rol', and 'quat'.

locusPlot(sc, ryplot)

Plot interpolated yaw, pitch, and roll over the full locus time span.

Produces a ryscene-quatslerp.png figure showing the three Euler angles sampled at 50 uniformly-spaced times across the locus range, annotated with the raw locus table.

Parameters:

• sc – A Scene instance with dfLocus loaded.

• ryplot – The pyradi.ryplot module (passed explicitly to avoid a module-level import in production code).