giant.photometry.planning.ObservationPlanner

class giant.photometry.planning.ObservationPlanner(photometry_model, trajectory, magnitude_model, luminosity_function)

Bases: object

This class implements observation planning functionality for GIANT.

This class acts as a container for details about the target/camera that are not normally used for navigation purposes. It then exposes the ability to use this extra information for OpNav planning purposes.

This class contains and Photometry model and DiscetizedPhotometricTrajectory in order to execute planning operations on a target body over the trajectory.

The magnitude model and luminocity function are used to determine the size and brightness of the target as seen by the camera.

• predict_acquisition() - determine the minimum time over a DiscretizedTrajectory in which an SNR value is

  acquired.

• predict_exposure() - Determine the required exposure time needed to achieve an SNR value over each step of

  a DiscretizedTrajectory.

• predict_snr() - Determine the SNR of an image taken at each step in a DiscretizedTrajectory.

The following shows an example use of the ObservationPlanner type. First, let’s assume you already have a SceneObject set up for the target body (target_obj) and the sun (sun_obj) as well as a GIANT CameraModel (camera_model). After importing the planning and photometry packages, we’ll want to define our objects within a Scene. :

>>> from giant.photometry.planning import ObservationPlanner, DiscretizedTrajectory
>>> from giant.photometry.modelling import PhotometricCameraModel,scatteredLight, au, Photometry
>>> from giant.photometry.magnitude import LinearPhaseMagnitudeModel
>>> import numpy
>>> from datetime import timedelta, datetime
>>> target_scene = Scene(target_objs=[target_obj], light_obj=sun_obj)

Next, lets set up the photometric camera model with the proper inputs. This example uses a LLORRI camera.

>>> LORRI = PhotometricCameraModel(gain = 21.1, #electrons/dn, transfer_time = 0.01178, 
                        standard_mag = 18.97, bin_mode = 1, resolved_rows_threshold = 300,
                        name='lorri',dn_readnoise = 0.88, dn_rate_standard = 15816137,
                        dark_current=0.0003,psf_factor=0.1, camera_model = camera_model)

Next, we will set up a Photometry object with the Scene and PhotomertricCameraModel.

>>> photometry = Photometry(scene=targetdinkinesh_scene, 
                photometric_camera_model=LORRI))

Then, we will set up the trajectory as a DiscretizedTrajectory. This will place the scene in the camera frame for each time step specified. This will require a camera position function in order to place the scene in the correct frame. Note that it is assumed that the camera_position_function will return a position relative to the same central body used in the position_function for the target_obj. For demo purposes, our function will return a constant, but this is typically defined by spice routines.

>>> def camera_position_function(date):
... return numpy.array([-5, 6, 7])
>>> trajectory = DiscretizedTrajectory(scene=target_scene, camera_position_function, 
... start_bound = datetime(2025, 2, 16), stop_bound=datetime(2026, 2, 16), step_size=timedelta(hours=24))

Now, we need to set up a magnitude and luminocity function used to determine the magnitude and I over F of the target based on the phase angle. Again, for simplicity of the demo, these will be simple functions and models. We will use a different magnitude models for when the target is resolved and unresolved.

*** Note: the magnitude models must be set up as a PhaseMagnitudeModel object, a LinearPhaseMagnitudeModel and HGPhaseMagnitudeModel objects are already set up in giant. However, the user can create their own.

>>> def target_IoverF(target_index, photometry):
... phase_angle = photometry.scene.target_objs[target_index]
... return 1*np.cos(phase_angle)
>>> resolved_mag_model = LinearPhaseMagnitudeModel(phase_slope=0.4)
>>> unresolved_mag_model = LinearPhaseMagmitudeModel(phase_slope=0.8)

Finally, we can place all these objects into an ObservationPlanner.

>>> planner = ObservationPlanner(photometry_model = photometry, trajectory = trajectory, luminosity_function = LumPhaseTable,
    magnitude_model = {'unresolved': unresolved_mag_model,
                        'resolved': resolved_mag_model
                        },
)

Now that the planner is set up, you can use this to predict acquisition times, exposure times, and SNR.

>>> aqu_time, aqu_dist = planner.predict_acquisition(goal_snr=10, exposure_time=5)
>>> exp, snr = planner.predict_exposure(goal_snr=10, exposure_time_guess=5)
>>> snr = planner.predict_snr(exposure_time=5)

Parameters:

• photometry_model (Photometry) – giant.photometry.Photometry object containing the scene to plan with

• trajectory (DiscretizedTrajectory) – DiscretizedPhotometricTrajectory object containing the span in which to search the trajectory

• magnitude_model (dict | list | PhaseMagnitudeModel) – A PhaseMagnitudeModel object that calculates the target magnitude based on the phase angle of the current trajectory

• luminosity_function (Callable) – A function with positional arguments (target_index : int, photometry : Photometry) to return the I over F of the target based on geometry and camera model

photometry_model

giant.photometry.Photometry object containing the scene to plan with search the trajectory

trajectory

DiscretizedPhotometricTrajectory object containing the span in which to search the trajectory

luminosity_function

A function with positional arguments (target_index : int, photometry : Photometry) to return the I over F of the target based on geometry and camera model

property magnitude_model

A PhaseMagnitudeModel object that calculates the target magnitude based on the phase angle of the current trajectory

Summary of Methods

predict_acquisition	Predicts the acquisition distance (and approximate time) for the desired SNR.
predict_exposure	Optimize the exposure time based on the required/goal signal-to-noise ratio
predict_snr	Calculate the SNR for each step along the trajectory with a provided exposure time