public final class DelayedTerrainAzimuthElevationMask extends Object implements IAzimuthElevationMask, IThreadAware
TerrainProvider.
Instead of computing the terrain horizon all at once, the values bounding a given azimuth will
be computed upon the first request for their values. In many cases, this can decrease
the amount of calculation required if only a small swath of the field of view is required.
An Azimuth-Elevation Mask describes how the horizon looks to a stationary object. It holds the maximum obscured elevation angle in each sampled direction from the stationary object. It can also keep track of the maximum elevation angle as a function of the linear distance from the origin of the mask. For example, if the stationary object is in a canyon, objects also inside the canyon are visible at a very low elevation angle. However, objects past the canyon walls are only visible if they are at a much steeper elevation angle such that they are above the walls.
This IAzimuthElevationMask is a read-only collection of ElevationMask instances.
Each ElevationMask corresponds to a particular direction. The direction is described by the
Azimuth (get / set) property as an azimuth angle measured from North toward East.
The maximum obscured elevation angle in that direction is described by the Elevation (get / set) property.
Each ElevationMask instance is also a collection of ElevationRise instances,
each of which describes a change in the maximum obscured elevation angle along the ray. The ElevationRise
also records the linear distance from the origin of the mask to the obscured point along the given azimuth and elevation angles.
| Constructor and Description |
|---|
DelayedTerrainAzimuthElevationMask(TerrainProvider provider,
Cartographic position,
double maxSearchAngle,
double stepSize,
int numberOfAzimuthSteps)
Create a new instance of the mask based on the given terrain.
|
DelayedTerrainAzimuthElevationMask(TerrainProvider provider,
double minimumTerrainHeight,
double maximumTerrainHeight,
Cartographic position,
double maxSearchAngle,
double stepSize,
int numberOfAzimuthSteps)
Create a new instance of the mask based on the given terrain.
|
| Modifier and Type | Method and Description |
|---|---|
Object |
clone(CopyContext context)
Clones this object using the specified context.
|
boolean |
contains(ElevationMask item)
Determine whether the requested item is in this azimuth elevation mask.
|
void |
copyTo(ElevationMask[] array,
int arrayIndex)
Copies the
ElevationMask values to the given array. |
ElevationMask |
get(int index)
Gets the element at the specified index.
|
CentralBody |
getCentralBody()
Gets the central body to which this mask is relative.
|
int |
getCount()
Gets the number of
ElevationMask objects in this azimuth elevation mask. |
boolean |
getIsThreadSafe()
Gets a value indicating whether the methods on this instance are safe to call from
multiple threads simultaneously.
|
double |
getMaximumObscuredElevation(double azimuth,
double distance)
Computes the maximum elevation angle that is obscured as of a specified distance
along an azimuth ray.
|
Cartographic |
getPosition()
Gets the planetodetic position of the observer for the mask.
|
int |
indexOf(ElevationMask item)
Returns the index of the given item in the azimuth elevation mask.
|
Iterator<ElevationMask> |
iterator()
Returns an enumerator that iterates through the collection.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitforEach, spliteratorpublic DelayedTerrainAzimuthElevationMask(@Nonnull TerrainProvider provider, @Nonnull Cartographic position, double maxSearchAngle, double stepSize, int numberOfAzimuthSteps)
provider - The terrain which defines the horizon at the given position.position - The planetodetic position at which to compute the surrounding mask.maxSearchAngle - The maximum angle, in radians measured from the center of the Ellipsoid,
to move along each azimuth ray in constructing the mask.stepSize - The size of the step along each azimuth ray, measured from the center of the
Ellipsoid in radians.numberOfAzimuthSteps - The number of azimuth steps to use to compute the mask.
This will define the resolution of the mask around the horizon.ArgumentNullException - Thrown if provider is null.ArgumentOutOfRangeException - Thrown if numberOfAzimuthSteps is less than or equal to zero.public DelayedTerrainAzimuthElevationMask(@Nonnull TerrainProvider provider, double minimumTerrainHeight, double maximumTerrainHeight, @Nonnull Cartographic position, double maxSearchAngle, double stepSize, int numberOfAzimuthSteps)
provider - The terrain which defines the horizon at the given position.minimumTerrainHeight - The minimum height in meters that can be returned by the
TerrainProvider's
TerrainProvider.getHeightRelativeToShape(double, double) method.
Setting this value lower than necessary will not affect the results, but it will decrease
performance. Setting it too high can cause incorrect results.maximumTerrainHeight - The maximum height in meters that can be returned by the
TerrainProvider's
TerrainProvider.getHeightRelativeToShape(double, double) method.
Setting this value higher than necessary will not affect the results, but it will decrease
performance. Setting it too low can cause incorrect results.position - The planetodetic position at which to compute the surrounding mask.maxSearchAngle - The maximum angle, in radians measured from the center of the Ellipsoid,
to move along each azimuth ray in constructing the mask.stepSize - The size of the step along each azimuth ray, measured from the center of the
Ellipsoid in radians.numberOfAzimuthSteps - The number of azimuth steps to use to compute the mask.
This will define the resolution of the mask around the horizon.ArgumentNullException - Thrown if provider is null.ArgumentOutOfRangeException - Thrown if numberOfAzimuthSteps is less than or equal to zero.public final Object clone(CopyContext context)
This method should be implemented to call a copy constructor on the class of the
object being cloned. The copy constructor should take the CopyContext as a parameter
in addition to the existing instance to copy. The copy constructor should first call
CopyContext.addObjectMapping(T, T) to identify the newly constructed instance
as a copy of the existing instance. It should then copy all fields, using
CopyContext.updateReference(T) to copy any reference fields.
A typical implementation of ICloneWithContext:
public static class MyClass implements ICloneWithContext {
public MyClass(MyClass existingInstance, CopyContext context) {
context.addObjectMapping(existingInstance, this);
someReference = context.updateReference(existingInstance.someReference);
}
@Override
public final Object clone(CopyContext context) {
return new MyClass(this, context);
}
private Object someReference;
}
In general, all fields that are reference types should be copied with a call to
CopyContext.updateReference(T). There are a couple of exceptions:
If one of these exceptions applies, the CopyContext should be given an opportunity
to update the reference before the reference is copied explicitly. Use
CopyContext.updateReference(T) to update the reference. If CopyContext.updateReference(T) returns
the original object, indicating that the context does not have a replacement registered,
then copy the object manually by invoking a Clone method, a copy constructor, or by manually
constructing a new instance and copying the values.
alwaysCopy = context.updateReference(existingInstance.alwaysCopy);
if (existingInstance.alwaysCopy != null && alwaysCopy == existingInstance.alwaysCopy) {
alwaysCopy = (AlwaysCopy) existingInstance.alwaysCopy.clone(context);
}
If you are implementing an evaluator (a class that implements IEvaluator), the
IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) method shares some responsibilities with the
copy context constructor. Code duplication can be avoided by doing the following:
CopyContext.updateReference(T). You should still call CopyContext.updateReference(T) on any references to
non-evaluators.
IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as the last line in the constructor and pass it the
same CopyContext passed to the constructor.
IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) as normal. See the reference documentation for
IEvaluator.updateEvaluatorReferences(agi.foundation.infrastructure.CopyContext) for more information on implementing that method.
public MyClass(MyClass existingInstance, CopyContext context) {
super(existingInstance, context);
someReference = context.updateReference(existingInstance.someReference);
evaluatorReference = existingInstance.evaluatorReference;
updateEvaluatorReferences(context);
}
@Override
public void updateEvaluatorReferences(CopyContext context) {
evaluatorReference = context.updateReference(evaluatorReference);
}
@Override
public Object clone(CopyContext context) {
return new MyClass(this, context);
}
private Object someReference;
private IEvaluator evaluatorReference;clone in interface ICloneWithContextcontext - The context to use to perform the copy.public final boolean getIsThreadSafe()
If this property is true, all methods and properties are guaranteed to be thread safe.
Conceptually, an object that returns true for this method acts as if there is a lock
protecting each method and property such that only one thread at a time can be inside any method or
property in the class. In reality, such locks are generally not used and are in fact discouraged. However,
the user must not experience any exceptions or inconsistent behavior that would not be experienced if such
locks were used.
If this property is false, the behavior when using this class from multiple threads
simultaneously is undefined and may include inconsistent results and exceptions. Clients wishing to use
multiple threads should call CopyForAnotherThread.copy(T) to get a separate instance of the
object for each thread.
getIsThreadSafe in interface IThreadAwarepublic final double getMaximumObscuredElevation(double azimuth,
double distance)
ElevationMask
instances bounding the given azimuth that haven't been computed yet.getMaximumObscuredElevation in interface IAzimuthElevationMaskazimuth - The azimuth, in radians.distance - The maximum distance along the azimuth ray to consider.@Nonnull public final Cartographic getPosition()
getPosition in interface IAzimuthElevationMaskpublic final CentralBody getCentralBody()
getCentralBody in interface IAzimuthElevationMaskpublic final int indexOf(ElevationMask item)
item - The requested item to locate.public final ElevationMask get(int index)
index - The zero-based index of the element to get.public final boolean contains(ElevationMask item)
item - The item to locate in the mask.true if the item is found; otherwise false.public final void copyTo(ElevationMask[] array, int arrayIndex)
ElevationMask values to the given array.
If any of the values are not yet computed, they will be computed before copying them
to the array.array - The one-dimensional array that is the destination of the elements.arrayIndex - The zero-based index in array at which copying begins.public final int getCount()
ElevationMask objects in this azimuth elevation mask.public final Iterator<ElevationMask> iterator()
iterator in interface Iterable<ElevationMask>