agi.foundation.celestial

(agi.foundation.models-2025r1.jar)

Class ScalarOccultation

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.geometry.Scalar

agi.foundation.celestial.ScalarOccultation

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

Direct Known Subclasses:

ScalarOccultationCylindrical, ScalarOccultationDualCone, ScalarOccultationNoShadow

public abstract class ScalarOccultation
extends Scalar

A class that provides evaluators for percentage of occultation/eclipse at a position, as well as EclipseType.

The percentage runs from 0.0 (completely lit) to 1.0 (total eclipse).

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ScalarOccultation() Creates a new Scalar with a VectorType (get / set) of RadiationVectorType.CORRECT_FOR_LIGHT_TIME_DELAY_AND_ABERRATION.
protected	ScalarOccultation(CentralBody illuminatingBody, Point targetPoint, CentralBody... occludingBodies) Creates a new Scalar from the given illuminating body, target point, and occluding bodies.
protected	ScalarOccultation(CentralBody illuminatingBody, Point targetPoint, Iterable<CentralBody> occludingBodies) Creates a new Scalar from the given illuminating body, target point, and occluding bodies.
protected	ScalarOccultation(ScalarOccultation existingInstance, CopyContext context) Initializes a new instance as a copy of an existing instance.

Method Summary

Modifier and Type	Method and Description
protected boolean	checkForSameDefinition(Scalar other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected abstract boolean	checkForSameDefinition(ScalarOccultation other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected int	computeCurrentDefinitionHashCode() Computes a hash code based on the current properties of this object.
protected void	createEvaluatorHelper(EvaluatorGroup group, RadiationVectorType vectorType, ArrayList<VectorEvaluator>[] platformToOccluding, ArrayList<VectorEvaluator>[] platformToIlluminating, ArrayList<Ellipsoid>[] occludingShapes, Ellipsoid[] illuminatingShape) Checks all properties and creates the vectors required to evaluate occultation fractions.
protected static double[]	eclipseAngles(Ellipsoid eclipsingBody, Cartesian platformToEclipsing, Cartesian platformToIlluminating, Ellipsoid illuminatingBody) Returns the angles needed for the various eclipse calculations in the format [relative angle, eclipse body half angle, illuminating body half angle].
void	enumerateDependencies(DependencyEnumerator enumerator) Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon.
List<Evaluator<EclipseType>>	getEclipseTypeEvaluators() Gets an evaluator to calculate EclipseType for every CentralBody in OccludingBodies (get).
abstract List<Evaluator<EclipseType>>	getEclipseTypeEvaluators(EvaluatorGroup group) Gets an evaluator to calculate EclipseType for every CentralBody in OccludingBodies (get).
CentralBody	getIlluminatingBody() Gets the body to use for the illuminating body (commonly the sun).
ReferenceFrame	getInertialFrame() Gets or sets an alternate inertial reference frame.
List<CentralBody>	getOccludingBodies() Gets a list of bodies which obscure the illuminating body.
Point	getTargetPoint() Gets the Point representing the location at which the occultation factor is being calculated.
RadiationVectorType	getVectorType() Gets whether or not to use true position to calculate the occultation, or apparent position adjusted for aberration.
void	setIlluminatingBody(CentralBody value) Sets the body to use for the illuminating body (commonly the sun).
void	setInertialFrame(ReferenceFrame value) Gets or sets an alternate inertial reference frame.
void	setTargetPoint(Point value) Sets the Point representing the location at which the occultation factor is being calculated.
void	setVectorType(RadiationVectorType value) Sets whether or not to use true position to calculate the occultation, or apparent position adjusted for aberration.

Methods inherited from class agi.foundation.geometry.Scalar

add, add, add, add, add, checkForSameDefinition, createScalarDerivative, divide, divide, divide, divide, divide, getEvaluator, getEvaluator, multiply, multiply, multiply, multiply, multiply, power, subtract, subtract, subtract, subtract, subtract, toScalar

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, clone, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, freeze, freezeAggregatedObjects, getCollectionHashCode, getCollectionHashCode, getCollectionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDefinitionHashCode, getDictionaryHashCode, getIsFrozen, isSameDefinition, throwIfFrozen

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ScalarOccultation

protected ScalarOccultation()

Creates a new Scalar with a VectorType (get / set) of RadiationVectorType.CORRECT_FOR_LIGHT_TIME_DELAY_AND_ABERRATION. IlluminatingBody (get / set) and TargetPoint (get / set) must be set before an Evaluator is created, and generally at least one body should be added to OccludingBodies (get).

ScalarOccultation

protected ScalarOccultation(CentralBody illuminatingBody,
                            Point targetPoint,
                            @Nonnull
                            CentralBody... occludingBodies)

Creates a new Scalar from the given illuminating body, target point, and occluding bodies.

Parameters:

illuminatingBody - The illuminating body.

targetPoint - The target point.

occludingBodies - The occluding bodies.

ScalarOccultation

protected ScalarOccultation(CentralBody illuminatingBody,
                            Point targetPoint,
                            @Nonnull
                            Iterable<CentralBody> occludingBodies)

Creates a new Scalar from the given illuminating body, target point, and occluding bodies.

Parameters:

illuminatingBody - The illuminating body.

targetPoint - The target point.

occludingBodies - The occluding bodies.

ScalarOccultation

protected ScalarOccultation(@Nonnull
                            ScalarOccultation existingInstance,
                            @Nonnull
                            CopyContext context)

Initializes a new instance as a copy of an existing instance.

See ICloneWithContext.clone(CopyContext) for more information about how to implement this constructor in a derived class.

Parameters:

existingInstance - The existing instance to copy.

context - A CopyContext that controls the depth of the copy.

Throws:

ArgumentNullException - Thrown when existingInstance or context is null.

Method Detail

checkForSameDefinition

protected final boolean checkForSameDefinition(Scalar other)

Checks to determine if another instance has the same definition as this instance and returns true if it does. Derived classes MUST override this method and check all new fields introduced by the derived class for definitional equivalence. It is NOT necessary to check base class fields because the base class will already have done that. When overriding this method, you should NOT call the base implementation because it will return false for all derived-class instances. Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).

Specified by:

checkForSameDefinition in class Scalar

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

checkForSameDefinition

protected abstract boolean checkForSameDefinition(ScalarOccultation other)

Checks to determine if another instance has the same definition as this instance and returns true if it does. Derived classes MUST override this method and check all new fields introduced by the derived class for definitional equivalence. It is NOT necessary to check base class fields because the base class will already have done that. When overriding this method, you should NOT call the base implementation because it will return false for all derived-class instances. Derived classes should check the type of other to preserve the symmetric nature of IEquatableDefinition.isSameDefinition(java.lang.Object).

Parameters:

other - The other instance to compare to this one.

Returns:

true if the two objects are defined equivalently; otherwise false.

computeCurrentDefinitionHashCode

protected int computeCurrentDefinitionHashCode()

Computes a hash code based on the current properties of this object. Derived classes MUST override this method and compute a hash code that combines: a unique hash code seed, the base implementation result, and the hash codes of all new fields introduced by the derived class which are used in the ScalarOccultation.checkForSameDefinition(agi.foundation.geometry.Scalar) method.

Overrides:

computeCurrentDefinitionHashCode in class Scalar

Returns:

The computed hash code.

enumerateDependencies

public void enumerateDependencies(DependencyEnumerator enumerator)

Enumerates the dependencies of this object by calling DependencyEnumerator#enumerate(T) for each object that this object directly depends upon. Derived classes which contain additional dependencies MUST override this method, call the base implementation, and enumerate dependencies introduced by the derived class.

Specified by:

enumerateDependencies in interface IEnumerateDependencies

Overrides:

enumerateDependencies in class DefinitionalObject

Parameters:

enumerator - The enumerator that is informed of the dependencies of this object.

getTargetPoint

public final Point getTargetPoint()

Gets the Point representing the location at which the occultation factor is being calculated.

setTargetPoint

public final void setTargetPoint(Point value)

Sets the Point representing the location at which the occultation factor is being calculated.

getIlluminatingBody

public final CentralBody getIlluminatingBody()

Gets the body to use for the illuminating body (commonly the sun).

setIlluminatingBody

public final void setIlluminatingBody(CentralBody value)

Sets the body to use for the illuminating body (commonly the sun).

getInertialFrame

public final ReferenceFrame getInertialFrame()

Gets or sets an alternate inertial reference frame. This property is null by default, and if it remains null, then the InertialFrame (get / set) of the IlluminatingBody (get / set) will be used.

The inertial frame is used to correct the position vectors for light time delay and aberration if the appropriate RadiationVectorType is set.

setInertialFrame

public final void setInertialFrame(ReferenceFrame value)

Gets or sets an alternate inertial reference frame. This property is null by default, and if it remains null, then the InertialFrame (get / set) of the IlluminatingBody (get / set) will be used.

The inertial frame is used to correct the position vectors for light time delay and aberration if the appropriate RadiationVectorType is set.

getOccludingBodies

@Nonnull
public final List<CentralBody> getOccludingBodies()

Gets a list of bodies which obscure the illuminating body.

getVectorType

@Nonnull
public final RadiationVectorType getVectorType()

Gets whether or not to use true position to calculate the occultation, or apparent position adjusted for aberration. By default set to RadiationVectorType.CORRECT_FOR_LIGHT_TIME_DELAY_AND_ABERRATION.

setVectorType

public final void setVectorType(@Nonnull
                                RadiationVectorType value)

Sets whether or not to use true position to calculate the occultation, or apparent position adjusted for aberration. By default set to RadiationVectorType.CORRECT_FOR_LIGHT_TIME_DELAY_AND_ABERRATION.

eclipseAngles

@Nonnull
protected static double[] eclipseAngles(@Nonnull
                                                  Ellipsoid eclipsingBody,
                                                  @Nonnull
                                                  Cartesian platformToEclipsing,
                                                  @Nonnull
                                                  Cartesian platformToIlluminating,
                                                  @Nonnull
                                                  Ellipsoid illuminatingBody)

Returns the angles needed for the various eclipse calculations in the format [relative angle, eclipse body half angle, illuminating body half angle].

Parameters:

eclipsingBody - The eclipsing body.

platformToEclipsing - The vector from the platform to the eclipsing body, in the fixed frame of the eclipsing body.

platformToIlluminating - The vector from the platform to the illuminating body, in the fixed frame of the eclipsing body.

illuminatingBody - The illuminating body.

Returns:

An array with the relative angle, and angular radii of the eclipsing and illuminating body.

getEclipseTypeEvaluators

@Nonnull
public abstract List<Evaluator<EclipseType>> getEclipseTypeEvaluators(@Nonnull
                                                                                EvaluatorGroup group)

Gets an evaluator to calculate EclipseType for every CentralBody in OccludingBodies (get).

Parameters:

group - The group with which to associate the new evaluator. By grouping evaluators that are often evaluated at the same Julian dates, common computations can be performed only once for the entire group instead of multiple times for each evaluator.

Returns:

An Evaluator of a list of EclipseType enums.

getEclipseTypeEvaluators

@Nonnull
public final List<Evaluator<EclipseType>> getEclipseTypeEvaluators()

Gets an evaluator to calculate EclipseType for every CentralBody in OccludingBodies (get).

Returns:

An Evaluator of a list of EclipseType enums.

createEvaluatorHelper

protected final void createEvaluatorHelper(EvaluatorGroup group,
                                           @Nonnull
                                           RadiationVectorType vectorType,
                                           @Nonnull
                                           ArrayList<VectorEvaluator>[] platformToOccluding,
                                           @Nonnull
                                           ArrayList<VectorEvaluator>[] platformToIlluminating,
                                           @Nonnull
                                           ArrayList<Ellipsoid>[] occludingShapes,
                                           @Nonnull
                                           Ellipsoid[] illuminatingShape)

Checks all properties and creates the vectors required to evaluate occultation fractions.

Parameters:

group - The group used for the created definitional objects.

vectorType - The type of the directional vector, which can be either true or account for aberration and light time delay.

platformToOccluding - A list of observer to occluding body vectors.

platformToIlluminating - A list of observer to the illuminating body vectors.

occludingShapes - A list of Ellipsoids that represent the occluding bodies.

illuminatingShape - The Ellipsoid that represents the illuminating shape.

Throws:

PropertyInvalidException - Thrown when TargetPoint (get / set), IlluminatingBody (get / set), OccludingBodies (get), or any occluding body is null.