Ellipsoid

giant.ray_tracer.shapes.ellipsoid:

class giant.ray_tracer.shapes.ellipsoid.Ellipsoid(self, center, principal_axes=None, orientation=None, ellipsoid_matrix=None, albedo_map=None, _bounding_box=None, _id=None)

A shape for modelling spheres and triaxial ellipsoidal bodies.

Most of the large objects in the solar system are generally ellipsoidal in shape. Therefore, when rendering these objects it can be much more efficient to actually model them as a triaxial ellipsoid, which can generally be traced more efficiently than even a KDTree due to having only 1 surface to check. Therefore, when you’re dealing with a shape well modeled by a triaxial ellipsoid it is recommended that you use this class.

This class works like other Shape classes in GIANT. It provides trace() and compute_intersect() for calculating the intersect between the object and a ray. It provides methods find_limbs() and compute_limb_jacobian() to identify points along the limb of the target and how those points change when the location of the observer is changed. In addition, it provides methods rotate() and translate() methods for moving the ellipsoid in the scene and an axis aligned bounding box in attribute bounding_box.

In GIANT the triaxial ellipsoid is represented in matrix form, that is:

\[\begin{split}\mathbf{A}_C = \mathbf{T}^{P}_{C}\left[\begin{array}{ccc} \frac{1}{a^2} & 0 & 0 \\ 0 & \frac{1}{b^2} & 0 \\ 0 & 0 & \frac{1}{c^2} \end{array}\right]\mathbf{T}_{P}^{C}\end{split}\]

Where \(\mathbf{A}_C\) is the ellipsoid matrix in the current frame \(C\), \(\mathbf{T}^P_C\) is the rotation matrix from the principal frame of the ellipsoid (\(P\), where the principal axes are aligned with the frame axes) to the current frame, and \(a\quad b\quad c\) are the lengths of the principal axes of the ellipsoid. From this class you can retrieve each component of the ellipsoid matrix. ellipsoid_matrix gives \(\mathbf{A}_C\), principal_axes gives \(a\quad b\quad c\quad\) as a length 3 array, and orientation gives \(\mathbf{T}_C^P\) as a 3x3 rotation matrix. In addition, the center of the ellipsoid in the current frame is in attribute center.

In addition to being its own object in a scene, the Ellipsoid class is also used to represent the Surface.reference_ellipsoid for a surface (used when doing limb based nav with irregular bodies in limb_matching as well as the SceneObject.circumscribing_sphere attribute of a scene object which is used to determine which pixels need traced for a specific object in the scene.

To initialize this class, you can either provide the ellipsoid matrix itself (which will be decomposed into its components), the principal axes themselves (in which case it will be assumed the object is currently in its principle frame), the principal axes and the orientation, or all 3 (though note that if its all 3 we don’t check to be sure they’re consistent). Also, note that any parameters beginning with an _ in the init method are primarily for pickling/unpickling the object and can mostly be ignored by the user.

Parameters:

• center (Optional[ARRAY_LIKE]) – The center of the ellipsoid in the current frame as a length 3 array

• principal_axes (Optional[ARRAY_LIKE]) – The length of each principal axis of the ellipsoid as a length 3 array

• orientation (Optional[ARRAY_LIKE]) – The rotation matrix from the principal frame for the ellipsoid to the current frame.

• ellipsoid_matrix (Optional[ARRAY_LIKE]) – The full 3x3 ellipsoid matrix as defined above

• albedo_map (Optional[Callable[[np.ndarray], np.ndarray]]) – The albedo map for the ellipsoid. This should take the form of a callable object which takes in an nx2 array of latitude/longitude in radians and returns a length n array of the albedo values for each point.

• _bounding_box (Optional[ARRAY_LIKE]) – The AxisAlignedBoundingBox for the ellipsoid. This is typically just used for pickling/unpickling

• _id (int) – The unique id for the ellipsoid object. This is typically only used for pickling/unpickling.

bounding_box: AxisAlignedBoundingBox

The AxisAlignedBoundingBox that fully contains this Ellipsoid.

id: int

The unique identifier for this ellipsoid as an integer.

albedo_map: Callable[[numpy.ndarray], numpy.ndarray] | None

The albedo map for the ellipsoid as a callable object which takes in an nx2 array of latitude/longitude in radians and returns a length n array of the albedo values for each point.

Typically this is an instance of scipy.interpolate.RegularGridInterpolator or similar.

center

The location of the center of th ellipsoid in the current frame as a length 3 numpy array.

ellipsoid_matrix

The ellipsoid matrix in the current frame for the ellipsoid as a 3x3 numpy array.

Mathematically this is given by:

\[\begin{split}\mathbf{A}_C = \mathbf{T}^{P}_{C}\left[\begin{array}{ccc} \frac{1}{a^2} & 0 & 0 \\ 0 & \frac{1}{b^2} & 0 \\ 0 & 0 & \frac{1}{c^2} \end{array}\right]\mathbf{T}_{P}^{C}\end{split}\]

Where \(\mathbf{A}_C\) is the ellipsoid matrix in the current frame \(C\), \(\mathbf{T}^P_C\) is the rotation matrix from the principal frame of the ellipsoid (\(P\), where the principal axes are aligned with the frame axes) to the current frame, and \(a\quad b\quad c\) are the lengths of the principal axes of the ellipsoid.

orientation

The rotation matrix from the principal axis frame to the current frame for the ellipsoid as a 3x3 numpy array.

principal_axes

The lengths of the principal axes of the ellipsoid as a length 3 numpy array

Summary of Methods

compute_albedos	This method computes the surface albedo for a location on the surface of the ellipsoid expressed in the principal frame of the ellipsoid.
compute_bounding_box	This method computes the AABB for the ellipsoid.
compute_intersect	This method computes the intersect between a single ray and the ellipsoid, returning an INTERSECT_DTYPE numpy array with the intersect location, surface normal at the intersect, and surface albedo at the intersect.
compute_limb_jacobian	This method computes the linear change in the limb location given a change in the relative position between the ellipsoid and the observer.
compute_normals	This method computes the local surface normal for a location on the surface of the ellipsoid.
find_limbs	The method determines the limb points (visible edge of the ellipsoid) that would be an observed for an observer located at observer_position looking toward scan_center_dir along the directions given by scan_dirs.
intersect	This method determines where the provides rays strike this tri-axial ellipsoid.
rotate	This method rotates the ellipsoid into a new frame.
trace	This method computes the intersect between rays and the ellipsoid, returning an INTERSECT_DTYPE numpy array with the intersect locations, surface normals at the intersects, and surface albedos at the intersects.
translate	This method translates the ellipsoid center.