Spherical Plotting utility

Overview

Please note that all Mayavi-based plotting functions have been commented out. Mayavi is not available for Python 3 in standard environments. The commented blocks are retained as documentation of the original capabilities and may be restored if Mayavi support is re-introduced.

This module provides tools for creating and viewing spherical plots.

The spherical plotting tool requires two sets of data to create the spherical plot: the vertex locations in (x, y, z) and the spatial relationship between the vertices (triangulation of nearest neighbours). This spatial relationship is required to create surface elements between the vertices.

The easiest way to create the spatial relationships between the vertices is to use a convex-hull polygon model of an object. The polygon or wireframe model has the required vertices and spatial relationships.

In the original application, a series of spheres were created using MeshLab with vertices equidistant over the surface (optimal spatial sampling). The files were exported as OFF files and should be in the pyradi data/plotspherical directory. There are 6 possible input files, each with a different number of samples on the unit sphere: 12, 42, 162, 642, 2562, 10242.

Any object with the required vertices and spatial relationships can be used; it does not have to be an equi-sampled sphere.

Note that the spherical plot has no way to discriminate between negative values and a pi phase shift: there is confusion between sign and direction. This is inherent in the conversion between Cartesian and spherical coordinates. The user must make provision for this, possibly by plotting only negative or only positive values.

The data must be in the OFF wireframe format.

There are two possible trajectory file types:

  • ‘Rotate’ — Stationary sensor and object with the target rotating. The trajectory file specifies the target trajectory.

  • ‘Orbit’ — Stationary object with an orbiting sensor. The trajectory file specifies the sensor trajectory.

The sphere data available in pyradi/data/plotspherical are:

Filename

Resolution

Number

Number

.

(degrees)

points

triangles

sphere_0_12

63.4

12

20

sphere_1_42

33.9

42

80

sphere_2_162

17.2

162

320

sphere_3_642

8.6

642

1280

sphere_4_2562

4.32

2562

5120

sphere_5_10242

2.16

10242

20480

sphere_6_40962

1.08

40962

81920

sphere_7_163842

0.54

163842

327680

The workflow is as follows:

  1. Use writeOSSIMTrajOFFFile (or your own equivalent) to calculate the appropriate trajectory file. Two additional files (vertices and triangles) are also created — keep these safe.

  2. Create your data set (e.g. run a simulation) using the trajectory file. Collect the simulation data in a format suitable for plotting.

  3. Use the simulation data together with the triangles and vertices files to plot the data. The triangles and vertices set up the three-dimensional grid; the simulation data provides the values to be plotted on that grid.

This tool was originally developed to create trajectory files for the Denel/CSIR OSSIM simulation. The code was restructured for greater universal application, but the final example is still an OSSIM case.

See the __main__ block for examples of use.

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

Module functions

readOffFile(filename)[source]

Read an OFF file and return the vertices and triangles as numpy arrays.

The OFF file is read and the data captured in the array structures.

Parameters:

filename (|) – path to the OFF file

Returns:

array of vertices, shape (N, 3) | triangles (np.array): array of triangle index triples, shape (M, 3) | Returns (None, None) if the file is not a valid OFF file or if the declared | vertex/face counts do not match the data.

Return type:

vertices (np.array)

Raises:

| No exception is raised. –

getRotateFromOffFile(filename, xPos, yPos, zPos)[source]

Read an OFF file and return object attitude and position for a rotating target.

Calculate the pitch and yaw angles to point the object’s X-axis towards each OFF file vertex direction.

Euler order is yaw-pitch-roll, with roll equal to zero. Yaw is defined in the xy plane. Pitch is defined in the xz plane. Roll is defined in the yz plane.

The object is assumed stationary at position (xPos, yPos, zPos). The position arrays have the same length as the attitude angle arrays, but all values in each individual array are identical.

Parameters:

  • filename (|) – OFF file path

  • xPos (|) – object position on the x axis

  • yPos (|) – object position on the y axis

  • zPos (|) – object position on the z axis

Returns:

array of x object location values | y (np.array): array of y object location values | z (np.array): array of z object location values | roll (np.array): array of object roll values (all zero) | pitch (np.array): array of object pitch values | yaw (np.array): array of object yaw values | vertices (np.array): array of vertices as [x y z] | triangles (np.array): array of triangle index triples | Returns a tuple of eight None values if the OFF file is invalid.

Return type:

x (np.array)

Raises:

| No exception is raised. –

getOrbitFromOffFile(filename, xTargPos, yTargPos, zTargPos, distance)[source]

Read an OFF file and return sensor attitude and position for an orbiting sensor.

Calculate the sensor attitude and position such that the sensor always looks at the object located at (xTargPos, yTargPos, zTargPos) from a constant distance.

Euler order is yaw-pitch-roll, with roll equal to zero. Yaw is defined in the xy plane. Pitch is defined in the xz plane. Roll is defined in the yz plane.

The object is assumed stationary at position (xTargPos, yTargPos, zTargPos).

Parameters:

  • filename (|) – OFF file path

  • xTargPos (|) – x target object position (fixed)

  • yTargPos (|) – y target object position (fixed)

  • zTargPos (|) – z target object position (fixed)

  • distance (|) – range at which the sensor orbits the target

Returns:

array of x sensor position values | y (np.array): array of y sensor position values | z (np.array): array of z sensor position values | roll (np.array): array of sensor roll values (all zero) | pitch (np.array): array of sensor pitch values | yaw (np.array): array of sensor yaw values | vertices (np.array): array of vertices as [x y z] | triangles (np.array): array of triangle index triples | Returns a tuple of eight None values if the OFF file is invalid.

Return type:

x (np.array)

Raises:

| No exception is raised. –

writeOSSIMTrajOFFFile(filename, trajType, distance, xTargPos, yTargPos, zTargPos, xVel, yVel, zVel, engine, deltaTime)[source]

Read an OFF file and write OSSIM trajectory files for a rotating object or orbiting sensor.

This function writes a file in the custom OSSIM trajectory file format. Use this function as an example of how to use the ryplotspherical functionality in your application.

Two different types of trajectory files are created:

  1. trajType = ‘Rotate’ Calculate attitude (pitch and yaw angles only, roll is zero) to orientate an object’s x-axis along the vertices in the OFF file. The location of the object is fixed at (xTargPos, yTargPos, zTargPos).

  2. trajType = ‘Orbit’ Calculate location and attitude (pitch and yaw angles only, roll is zero) of an orbiting sensor looking at a fixed location (xTargPos, yTargPos, zTargPos) from a given distance.

The velocity and engine settings are constant for all views.

Two additional files are also written to assist with subsequent viewing:

  1. The vertex file contains the normalised direction vectors between the object and observer.

  2. The triangles file defines the spatial linking between adjacent vectors, used when plotting the data.

Parameters:

  • filename (|) – OFF file path

  • trajType (|) – trajectory type — ‘Rotate’ or ‘Orbit’

  • distance (|) – distance from sensor to object

  • xTargPos (|) – object x position

  • yTargPos (|) – object y position

  • zTargPos (|) – object z position

  • xVel (|) – velocity in x direction

  • yVel (|) – velocity in y direction

  • zVel (|) – velocity in z direction

  • engine (|) – engine setting

  • deltaTime (|) – sampling time increment in output file

Returns:

Writes a trajectory .lut file, a triangles .dat file, and a vertices .dat file to the current directory.
Returns None for an unknown trajType.

Raises:

| No exception is raised. –

writeOSSIMTrajElevAzim(numSamplesAz, filename, trajType, distance, xTargPos, yTargPos, zTargPos, xVel, yVel, zVel, engine, deltaTime)[source]

Write OSSIM trajectory files for rotating object or orbiting sensor using elevation/azimuth sampling.

This function writes a file in the custom OSSIM trajectory file format using constant increments in azimuth and elevation (yaw and pitch).

Two different types of trajectory files are created:

  1. trajType = ‘Rotate’ Calculate attitude (pitch and yaw only, roll is zero) to orientate an object’s x-axis along the elevation and azimuth vectors. The location of the object is fixed at (xTargPos, yTargPos, zTargPos).

  2. trajType = ‘Orbit’ Calculate location and attitude (pitch and yaw only, roll is zero) of an orbiting sensor looking at a fixed location from a given distance, along the elevation and azimuth vectors.

The velocity and engine settings are constant for all views.

Two additional files are also written:

  1. The azimuth file contains sample values around the equator (0 to 2π).

  2. The elevation file contains sample values from north to south pole (−π/2 to +π/2).

Parameters:

  • numSamplesAz (|) – number of samples along the equator

  • filename (|) – output file base name

  • trajType (|) – trajectory type — ‘Rotate’ or ‘Orbit’

  • distance (|) – distance from sensor to object

  • xTargPos (|) – object x position

  • yTargPos (|) – object y position

  • zTargPos (|) – object z position

  • xVel (|) – velocity in x direction

  • yVel (|) – velocity in y direction

  • zVel (|) – velocity in z direction

  • engine (|) – engine setting

  • deltaTime (|) – sampling time increment in output file

Returns:

Writes a trajectory .lut file and an azimuth/elevation .dat file to the current directory.
Returns None for an unknown trajType.

Raises:

| No exception is raised. –

getRotateFromElevAzim(azimuth, elevation, xPos, yPos, zPos)[source]

Return object attitude and position for a rotating target on an azimuth/elevation grid.

Calculate the pitch and yaw angles to point the object’s X-axis towards each (azimuth, elevation) direction.

Euler order is yaw-pitch-roll, with roll equal to zero. Yaw is defined in the xy plane. Pitch is defined in the xz plane. Roll is defined in the yz plane.

The object is assumed stationary at position (xPos, yPos, zPos). The position arrays have the same length as the attitude angle arrays, but all values in each individual array are identical.

Parameters:

  • azimuth (|) – azimuth values in radians

  • elevation (|) – elevation values in radians

  • xPos (|) – object position on the x axis

  • yPos (|) – object position on the y axis

  • zPos (|) – object position on the z axis

Returns:

array of x object location values, shape (N*M, 1) | y (np.array): array of y object location values, shape (N*M, 1) | z (np.array): array of z object location values, shape (N*M, 1) | roll (np.array): array of object roll values (all zero), shape (N*M, 1) | pitch (np.array): array of object pitch values, shape (N*M, 1) | yaw (np.array): array of object yaw values, shape (N*M, 1) | azel (np.array): array of (azimuth, elevation) for each sample, shape (N*M, 2)

Return type:

x (np.array)

Raises:

| No exception is raised. –

getOrbitFromElevAzim(azimuth, elevation, xTargPos, yTargPos, zTargPos, distance)[source]

Return sensor attitude and position for an orbiting sensor on an azimuth/elevation grid.

Calculate the sensor attitude and position such that the sensor always looks at the object located at (xTargPos, yTargPos, zTargPos) from a constant distance, sampling at each (azimuth, elevation) grid point.

Euler order is yaw-pitch-roll, with roll equal to zero. Yaw is defined in the xy plane. Pitch is defined in the xz plane. Roll is defined in the yz plane.

The object is assumed stationary at position (xTargPos, yTargPos, zTargPos).

Parameters:

  • azimuth (|) – azimuth values in radians

  • elevation (|) – elevation values in radians

  • xTargPos (|) – x target object position (fixed)

  • yTargPos (|) – y target object position (fixed)

  • zTargPos (|) – z target object position (fixed)

  • distance (|) – range at which the sensor orbits the target

Returns:

array of x sensor position values, shape (N*M, 1) | y (np.array): array of y sensor position values, shape (N*M, 1) | z (np.array): array of z sensor position values, shape (N*M, 1) | roll (np.array): array of sensor roll values (all zero), shape (N*M, 1) | pitch (np.array): array of sensor pitch values, shape (N*M, 1) | yaw (np.array): array of sensor yaw values, shape (N*M, 1) | azel (np.array): array of (azimuth, elevation) for each sample, shape (N*M, 2)

Return type:

x (np.array)

Raises:

| No exception is raised. –