SceneObject

giant.ray_tracer.scene:

class giant.ray_tracer.scene.SceneObject(shape, current_position=None, current_orientation=None, name='object', position_function=None, orientation_function=None, corrections=CorrectionsType.LTPS)

This class provides a quick and easy interface for changing the position and orientation of various objects.

Essentially, this class adds position and orientation attributes to shapes, rays, KDTrees, and other objects that can be translated and rotated. It also adds optional orientation and position functions, which can be used to automatically set the position/orientation for this object at a given time using place(). This makes it much easier to perform frame transformations as the current frame’s orientation and origin are stored with the object. The position and orientation are specified with respect to the default fixed frame for the object, which is usually [0, 0, 0] and eye(3) respectively.

This class also provides 5 methods for updating the objects contained.

• change_position() - changes the position of the origin of the frame the object is expressed in. This works

  by first resetting the origin to 0 by subtracting off the previous origin, and then setting the new origin at the specified location. This is good when you are completely changing the frame the object is expressed in.

• translate() - This is similar to change_position() but it does not first reset the origin to 0. This

  is good for making updates to the frame the object is expressed in.

• change_orientation() - Changes the orientation of the frame the object is expressed in by first

  resetting the orientation to be the identity matrix by rotating by the inverse transformation of the previous orientation, and then rotating to the new orientation specified. This is good for when you are completely changing the frame the object is expressed in.

• rotate() - This is similar to change_orientation() but it does not first reset the orientation to the

  identity. This method is good for making updates to the frame the object is expressed in.

• place() - This automatically updates the orienation and position of the object based on the provided

  orientation_function and position_function. If either of these are still None then this will print a warning to the screen and do nothing

Note that this class does not intelligently relate frames to each other, that must be done by the user.

The following shows an example use of the SceneObj type. First, we want to change the frame we have the rays expressed in.

Start by doing your imports and setting up your ray in the camera frame:

>>> import giant.ray_tracer.rays as g_rays
>>> import giant.ray_tracer.scene as g_scene
>>> from giant.rotations import Rotation
>>> import numpy
>>> ray = g_rays.Rays([0, 0, 0], [-1, 0, 0])

Now, lets define a position and orientation function. Here for demo purposes we’ll just return constant values, though most commonly these are generated as spice function calls

>>> def position_function(date):
...     return numpy.array([-5, 6, 7])
>>> def orientation_function(date):
...     return Rotation([0.5, 2, -3.2])

Now we can create our SceneObj around the ray:

>>> scene_obj = g_scene.SceneObject(ray, position_function=position_function,
...                                 orientation_function=orientation_function)

Note here, that we are defining the default frame for the ray to be the current frame that it is in (the camera frame). This means that whenever we want to change the frame (not update) for the rays we need to specify the new origin and orientation with respect to the camera frame. Let’s change our rays to some new frame:

>>> new_loc = [1, 2, 3]  # the new origin location expressed in the original frame
>>> new_orientation = [4, 5, 6]  # the new orientation of the new frame with respect to the original frame

First, we’ll update the origin of the frame (we are assuming that new_loc is expressed in the camera frame here):

>>> scene_obj.change_position(new_loc)
>>> print(scene_obj.shape.start)
[ 1.  2.  3.]
>>> print(scene_obj.shape.direction)
[ -1.  0.  0.]

Now, we’ll change the orientation:

>>> scene_obj.change_orientation(new_orientation)
>>> print(scene_obj.shape.start)
[ 1.98283723  2.55366624  1.88338665]
>>> print(scene_obj.shape.direction)
[ 0.42296095 -0.05284171 -0.90460588]

Now lets say we want to update the current frame our ray is expressed in:

>>> update_pos = [0.05, -1, 0.2]  # where we want to move the current origin to expressed in the current frame
>>> scene_obj.translate(update_pos)
>>> print(scene_obj.shape.start)
[ 2.03283723  1.55366624  2.08338665]
>>> print(scene_obj.shape.direction)
[ 0.42296095 -0.05284171 -0.90460588

Note how this was added to the current frame, not reset back from the original frame:

>>> update_orientation = [0.001, 0.001, 0.001]
>>> scene_obj.rotate(update_orientation)
>>> print(scene_obj.shape.start)
[ 2.0323073   1.55371729  2.08386553]
>>> print(scene_obj.shape.direction)
[ 0.42381181 -0.05416946 -0.90412898]

Now, lets use the position function and orientation function we provided to update the rays position/orientation automatically

>>> scene_obj.place(datetime.datetime.utcnow())
>>> print(scene_obj.shape.start)
[-5.  6.  7.]
>>> print(scene_obj.shape.direction)
[ 0.75609837 -0.64204013 -0.12688471]

And finally, lets say that we want to return our ray to the initial frame:

>>> scene_obj.change_position([0, 0, 0])
>>> scene_obj.change_orientation(numpy.eye(3))
>>> print(scene_obj.shape.start)
[ 0.  0.  0.]
>>> print(scene_obj.shape.direction)
[ -1.  0.  0.]

Typically when using the position_function and orientation_function these should give the position of the object relative to the solar system bary center in the inertial frame and the rotation from the object fixed frame to the inertial frame respectively. This will then pair well with updating the scene to put everying in the camera frame if you also put the inertial camera position and rotation from the intertial frame to the camera frame on the OpNavImage as is typical. You can conceivably work differently than this but it is then up to you to ensure all of your definitions are consistent.

In addition to making it easy to move objects around in the scene, the SceneObject class also provides some useful methods for getting information about the object in the current scene. This includes get_bounding_pixels() which determines the extent of the object in the image (this only works once the object has been rotated/translated into the camera frame) and get_apparent_diamter() which predicts the apparent diameter of the object in pixels in the image (this also only works once the object has been rotated/translated into the camera frame).

Parameters:

• shape (Shape) – The shape that represents the object. This is typically a subclass of Shape, but can be anything so long as it implements translate, rotate, and trace methods.

• current_position (Sequence | ndarray | None) – The current position of the object in the current frame. If None then this will be assumed to be the origin.

• current_orientation (Rotation | Sequence | ndarray | None) – The current orientation of the object in the current frame. If None then this will be assumed to be the identity rotation

• name (str) – An identifying name for the object. This is simply for logging/readability purposes

• position_function (Callable[[<module 'datetime' from '/Users/aliounis/mambaforge/envs/giant_public/lib/python3.11/datetime.py'>], ndarray] | None) – A function which accepts a python datetime object and returns a 3 element array giving the position of the object at the requested time. usually this should return the position of the object with respect to the solar system bary center in the inertial frame. While this is not required, it is strongly encouraged in most cases

• orientation_function (Callable[[<module 'datetime' from '/Users/aliounis/mambaforge/envs/giant_public/lib/python3.11/datetime.py'>], Rotation] | None) – A function which accepts a python datetime object and returns a Rotation that gives the orientation of the object at the requested time. Usually this should return the rotation from the object fixed frame to the inertial frame. While this is not required, it is strongly encouraged in most cases

• corrections (CorrectionsType | None) – What corrections to apply when calculating the apparent location of the object in the camera frame. This should either be None for no corrections, or one of the enums from CorrectionsType, most typically CorrectionsTyps.LTPS which applies light time and stellar aberration corrections. This is used by Scene and is only used when the position_function and orientation_function are not None.

position_function: ndarray] | None

A function which accepts a python datetime object and returns a 3 element array giving the position of the object at the requested time.

Usually this should return the position of the object with respect to the solar system bary center in the inertial frame. While this is not required, it is strongly encouraged in most cases

orientation_function: Rotation] | None

A function which accepts a python datetime object and returns a Rotation that gives the orientation of the object at the requested time.

Usually this should return the rotation from the object fixed frame to the inertial frame. While this is not required, it is strongly encouraged in most cases

corrections: CorrectionsType | None

What corrections to apply when calculating the apparent location of the object in the camera frame.

This should either be None for no corrections, or one of the enums from CorrectionsType, most typically CorrectionsTyps.LTPS which applies light time and stellar aberration corrections. This is used by Scene and is only used when the position_function and orientation_function are not None.

name

The name of the object, used for logging purposes and readability.

property shape: Shape | Any

This is the shape of interest.

It is usually a Shape or object but the only requirement is that it have translate and rotate methods. Ideally it should also have a trace method, though this isn’t checked.

property position: ndarray

This is the current position of this object as a flat length 3 array

property orientation: Rotation

This is the current orientation of the frame this object is expressed in as a Rotation object

Summary of Methods

change_orientation	Change the orientation of the frame the object is expressed in.
change_position	Change the location of the object in the current frame.
get_apparent_diameter	Computes the apparent diameter for the given camera model and the current location.
get_bounding_pixels	Computes the bounding pixels for the given camera model and the current location.
place	Place the object using the orientation_function and position_function at the requested date.
rotate	Update the orientation of the frame the object and its location are expressed in.
translate	Update the location of the object in the current frame by adding a vector to the current location.