agi.foundation.coverage

(agi.foundation.spatial-2024r3.jar)

Class DiscreteCoverageDefinition

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.coverage.BaseCoverageDefinition

agi.foundation.coverage.DiscreteCoverageDefinition

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

Direct Known Subclasses:

MaterializedTemporallyPartitionedCoverageDefinition, ParameterizedTemporallyPartitionedCoverageDefinition

public abstract class DiscreteCoverageDefinition
extends BaseCoverageDefinition

This coverage definition provides a convenient way to organize and initialize a coverage calculation, which computes access calculations over a set of grid points. Each access calculation represents a logical operation determining whether a set of constraints are satisfied for geometry involving one grid point and any number of other assets. For more information, see the Coverage section of the documentation.

In contrast to the coverage definitions that inherit from ContinuousCoverageDefinition, which partition the calculation into groups of grid points, this coverage calculation will configure the grid to be evaluated in lock-step in time slices to take advantage of caching redundant calculations common among all grid points. The advantage of this approach is that it can significantly reduce the overall computation time in cases where Earth fixed-to-inertial frame calculations, communications network analysis, or other calculations largely independent of any particular grid point are needed. The calculation can also be configured with a larger or smaller timestep to trade off between overall run time and the resolution of the access calculations. If the step size is too small, coverage definitions derived from ContinuousCoverageDefinition may perform better by doing dynamic sampling over time rather than performing a large number of nearly-identical calculations. However, if the step size is too large, the discrete calculation may miss short intervals that are smaller than the stepsize.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DiscreteCoverageDefinition() Initializes a new instance with FindAccessBetweenSteps (get / set) set to true.
protected	DiscreteCoverageDefinition(DiscreteCoverageDefinition 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(BaseCoverageDefinition other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected abstract boolean	checkForSameDefinition(DiscreteCoverageDefinition other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
CoverageResults	computeCoverageOverTheGrid(JulianDate start, JulianDate stop, Duration step) Computes the CoverageResults which stores the results of this calculation for the whole grid.
CoverageResults	computeCoverageOverTheGrid(JulianDate start, JulianDate stop, Duration step, ITrackCalculationProgress tracker) Computes the CoverageResults which stores the results of this calculation for the whole grid.
CoverageResults	computeCoverageOverTheGrid(TimeIntervalCollection consideredIntervals, Duration step) Computes the CoverageResults which stores the results of this calculation for the whole grid.
CoverageResults	computeCoverageOverTheGrid(TimeIntervalCollection consideredIntervals, Duration step, ITrackCalculationProgress tracker) Computes the CoverageResults which stores the results of this calculation for the whole grid.
protected int	computeCurrentDefinitionHashCode() Computes a hash code based on the current properties of this object.
boolean	getFindAccessBetweenSteps() Gets a value indicating whether to perform additional access calculations between time steps where access was either gained or lost.
void	setFindAccessBetweenSteps(boolean value) Sets a value indicating whether to perform additional access calculations between time steps where access was either gained or lost.

Methods inherited from class agi.foundation.coverage.BaseCoverageDefinition

addAsset, addAsset, addAssetRange, checkForSameDefinition, createGridPoint, enumerateDependencies, freezeAggregatedObjects, getAssetDefinitions, getAssets, getFilter, getGrid, getGridPointService, getMultithreadCoverage, removeAllAssets, removeAsset, removeAsset, setAssetDefinitions, setFilter, setGrid, setGridPointService, setMultithreadCoverage, validateProperties

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, areSameDefinition, clone, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, collectionItemsAreSameDefinition, dictionaryItemsAreSameDefinition, freeze, 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

DiscreteCoverageDefinition

protected DiscreteCoverageDefinition()

Initializes a new instance with FindAccessBetweenSteps (get / set) set to true.

DiscreteCoverageDefinition

protected DiscreteCoverageDefinition(@Nonnull
                                     DiscreteCoverageDefinition 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(BaseCoverageDefinition 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 BaseCoverageDefinition

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(DiscreteCoverageDefinition 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 DiscreteCoverageDefinition.checkForSameDefinition(agi.foundation.coverage.BaseCoverageDefinition) method.

Overrides:

computeCurrentDefinitionHashCode in class BaseCoverageDefinition

Returns:

The computed hash code.

getFindAccessBetweenSteps

public final boolean getFindAccessBetweenSteps()

Gets a value indicating whether to perform additional access calculations between time steps where access was either gained or lost. If this is false, when a new step determines that access is now satisfied, the satisfied interval will begin at the time of that step. This defaults to true.

setFindAccessBetweenSteps

public final void setFindAccessBetweenSteps(boolean value)

Sets a value indicating whether to perform additional access calculations between time steps where access was either gained or lost. If this is false, when a new step determines that access is now satisfied, the satisfied interval will begin at the time of that step. This defaults to true.

computeCoverageOverTheGrid

public final CoverageResults computeCoverageOverTheGrid(@Nonnull
                                                        JulianDate start,
                                                        @Nonnull
                                                        JulianDate stop,
                                                        @Nonnull
                                                        Duration step)

Computes the CoverageResults which stores the results of this calculation for the whole grid. Results for each grid point are stored in a CoverageQueryResult, the collection of which is contained by the overall result. Call this method after setting up the Grid (get / set) and adding the desired Assets (get) to the definition.

Parameters:

start - The start time of the interval to consider.

stop - The stop time of the interval to consider.

step - The stepsize used to sample access.

Returns:

The result of computing coverage over the grid.

Throws:

PropertyInvalidException - Thrown if the Grid (get / set), BaseCoverageDefinition.GridPointService, or Filter (get / set) property is null. Also thrown if either GridPointCreationCallback (get / set) or GridPointPlaceholder (get / set) is null, depending upon which is relevant.

IllegalStateException -

Thrown in several circumstances:

No Assets (get) have been specified.

Duplicate Assets (get) were specified.

No grid points were generated with the supplied definition of Grid (get / set).

computeCoverageOverTheGrid

public final CoverageResults computeCoverageOverTheGrid(@Nonnull
                                                        JulianDate start,
                                                        @Nonnull
                                                        JulianDate stop,
                                                        @Nonnull
                                                        Duration step,
                                                        ITrackCalculationProgress tracker)

Computes the CoverageResults which stores the results of this calculation for the whole grid. Results for each grid point are stored in a CoverageQueryResult, the collection of which is contained by the overall result. Call this method after setting up the Grid (get / set) and adding the desired Assets (get) to the definition.

Parameters:

start - The start time of the interval to consider.

stop - The stop time of the interval to consider.

step - The stepsize used to sample access.

tracker - A tracker which can track the progress of the calculation and provides a way to smoothly cancel execution.

Returns:

The result of computing coverage over the grid.

Throws:

PropertyInvalidException - Thrown if the Grid (get / set), BaseCoverageDefinition.GridPointService, or Filter (get / set) property is null. Also thrown if either GridPointCreationCallback (get / set) or GridPointPlaceholder (get / set) is null, depending upon which is relevant.

IllegalStateException -

Thrown in several circumstances:

No Assets (get) have been specified.

Duplicate Assets (get) were specified.

No grid points were generated with the supplied definition of Grid (get / set).

computeCoverageOverTheGrid

public final CoverageResults computeCoverageOverTheGrid(TimeIntervalCollection consideredIntervals,
                                                        @Nonnull
                                                        Duration step)

Computes the CoverageResults which stores the results of this calculation for the whole grid. Results for each grid point are stored in a CoverageQueryResult, the collection of which is contained by the overall result. Call this method after setting up the Grid (get / set) and adding the desired Assets (get) to the definition.

Parameters:

consideredIntervals - The time intervals to consider for the coverage calculation.

step - The stepsize used to sample access.

Returns:

The result of computing coverage over the grid.

Throws:

PropertyInvalidException - Thrown if the Grid (get / set), BaseCoverageDefinition.GridPointService, or Filter (get / set) property is null. Also thrown if either GridPointCreationCallback (get / set) or GridPointPlaceholder (get / set) is null, depending upon which is relevant.

IllegalStateException -

Thrown in several circumstances:

No Assets (get) have been specified.

Duplicate Assets (get) were specified.

No grid points were generated with the supplied definition of Grid (get / set).

computeCoverageOverTheGrid

public final CoverageResults computeCoverageOverTheGrid(@Nonnull
                                                        TimeIntervalCollection consideredIntervals,
                                                        @Nonnull
                                                        Duration step,
                                                        @Nullable
                                                        ITrackCalculationProgress tracker)

Computes the CoverageResults which stores the results of this calculation for the whole grid. Results for each grid point are stored in a CoverageQueryResult, the collection of which is contained by the overall result. Call this method after setting up the Grid (get / set) and adding the desired Assets (get) to the definition.

Parameters:

consideredIntervals - The time intervals to consider for the coverage calculation.

step - The step size used to sample access.

tracker - A tracker which can track the progress of the calculation and provides a way to smoothly cancel execution.

Returns:

The result of computing coverage over the grid.

Throws:

PropertyInvalidException - Thrown if the Grid (get / set), BaseCoverageDefinition.GridPointService, or Filter (get / set) property is null. Also thrown if either GridPointCreationCallback (get / set) or GridPointPlaceholder (get / set) is null, depending upon which is relevant.

IllegalStateException -

Thrown in several circumstances:

No Assets (get) have been specified.

Duplicate Assets (get) were specified.

No grid points were generated with the supplied definition of Grid (get / set).