agi.foundation.terrain

(agi.foundation.terrainanalysis-2023r2.jar)

Class TerrainAlongLine

java.lang.Object

agi.foundation.terrain.TerrainAlongLine

public final class TerrainAlongLine
extends Object

Contains methods to discover terrain features along a straight line between two points.

Field Summary

Fields

Modifier and Type	Field and Description
static double	DefaultMaximumTerrainHeight The default value for the maximum height in meters that can be returned by a TerrainProvider's TerrainProvider.getHeightRelativeToShape(double, double) method.
static double	DefaultMinimumTerrainHeight The default value for the minimum height in meters that can be returned by a TerrainProvider's TerrainProvider.getHeightRelativeToShape(double, double) method.

Method Summary

Modifier and Type	Method and Description
static double	computeElevationAngleAboveTerrain(Cartesian observerPositionFixed, Cartesian targetPositionFixed, TerrainProvider terrainProvider) Computes the angle from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle.
static double	computeElevationAngleAboveTerrain(Cartesian observerPositionFixed, Cartesian targetPositionFixed, TerrainProvider terrainProvider, double minimumTerrainHeight, double maximumTerrainHeight) Computes the angle from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle.
static double	computeElevationAngleAboveTerrain(Cartographic observerPosition, Cartographic targetPosition, TerrainProvider terrainProvider) Computes the angle from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle.
static double	computeElevationAngleAboveTerrain(Cartographic observerPosition, Cartographic targetPosition, TerrainProvider terrainProvider, double minimumTerrainHeight, double maximumTerrainHeight) Computes the angle from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle.
static double	computeObstructionMetric(Cartesian observerPositionFixed, Cartesian targetPositionFixed, TerrainProvider terrainProvider, boolean findWorstObstruction, boolean findIndicatedExtremaPrecisely) Computes a metric value indicating the amount of obstruction from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle.
static double	computeObstructionMetric(Cartesian observerPositionFixed, Cartesian targetPositionFixed, TerrainProvider terrainProvider, double minimumTerrainHeight, double maximumTerrainHeight, boolean findWorstObstruction, boolean findIndicatedExtremaPrecisely) Computes a metric value indicating the amount of obstruction from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle.
static double	computeObstructionMetric(Cartographic observerPosition, Cartographic targetPosition, TerrainProvider terrainProvider, boolean findWorstObstruction, boolean findIndicatedExtremaPrecisely) Computes a metric value indicating the amount of obstruction from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle.
static double	computeObstructionMetric(Cartographic observerPosition, Cartographic targetPosition, TerrainProvider terrainProvider, double minimumTerrainHeight, double maximumTerrainHeight, boolean findWorstObstruction, boolean findIndicatedExtremaPrecisely) Computes a metric value indicating the amount of obstruction from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle.
static Cartesian	computePositionWithMaximumElevationAngle(Cartesian observerPositionFixed, Cartesian targetPositionFixed, TerrainProvider terrainProvider) Computes the point on terrain with the highest elevation angle between the observer and target positions from the perspective of the position closest to the Shape (get / set).
static Cartesian	computePositionWithMaximumElevationAngle(Cartesian observerPositionFixed, Cartesian targetPositionFixed, TerrainProvider terrainProvider, double minimumTerrainHeight, double maximumTerrainHeight) Computes the point on terrain with the highest elevation angle between the observer and target positions from the perspective of the position closest to the Shape (get / set).
static Cartesian	computePositionWithMaximumElevationAngle(Cartographic observerPosition, Cartographic targetPosition, TerrainProvider terrainProvider) Computes the point on terrain with the highest elevation angle between the observer and target positions from the perspective of the position closest to the Shape (get / set).
static Cartesian	computePositionWithMaximumElevationAngle(Cartographic observerPosition, Cartographic targetPosition, TerrainProvider terrainProvider, double minimumTerrainHeight, double maximumTerrainHeight) Computes the point on terrain with the highest elevation angle between the observer and target positions from the perspective of the position closest to the Shape (get / set).
static Cartographic	computeTerrainIntersection(Cartesian cartesian, Cartographic cartographic, UnitCartesian direction, double granularity, double maximumDistance, TerrainProvider terrainProvider) Computes the location of the first intersection with terrain from the provided location along the indicated direction.
static Cartographic	computeTerrainIntersection(Cartesian cartesian, Cartographic cartographic, UnitCartesian direction, double granularity, double maximumDistance, TerrainProvider terrainProvider, double minimumTerrainHeight, double maximumTerrainHeight) Computes the location of the first intersection with terrain from the provided location along the indicated direction.
static Cartographic	computeTerrainIntersection(Cartesian cartesian, UnitCartesian direction, double granularity, double maximumDistance, TerrainProvider terrainProvider) Computes the location of the first intersection with terrain from the provided location along the indicated direction.
static Cartographic	computeTerrainIntersection(Cartesian cartesian, UnitCartesian direction, double granularity, double maximumDistance, TerrainProvider terrainProvider, double minimumTerrainHeight, double maximumTerrainHeight) Computes the location of the first intersection with terrain from the provided location along the indicated direction.
static Cartographic	computeTerrainIntersection(Cartographic cartographic, UnitCartesian direction, double granularity, double maximumDistance, TerrainProvider terrainProvider) Computes the location of the first intersection with terrain from the provided location along the indicated direction.
static Cartographic	computeTerrainIntersection(Cartographic cartographic, UnitCartesian direction, double granularity, double maximumDistance, TerrainProvider terrainProvider, double minimumTerrainHeight, double maximumTerrainHeight) Computes the location of the first intersection with terrain from the provided location along the indicated direction.

Methods inherited from class java.lang.Object

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

Field Detail

DefaultMinimumTerrainHeight

public static final double DefaultMinimumTerrainHeight

The default value for the minimum height in meters that can be returned by a TerrainProvider's TerrainProvider.getHeightRelativeToShape(double, double) method.

See Also:

Constant Field Values

DefaultMaximumTerrainHeight

public static final double DefaultMaximumTerrainHeight

The default value for the maximum height in meters that can be returned by a TerrainProvider's TerrainProvider.getHeightRelativeToShape(double, double) method.

See Also:

Constant Field Values

Method Detail

computePositionWithMaximumElevationAngle

@Nonnull
public static Cartesian computePositionWithMaximumElevationAngle(@Nonnull
                                                                           Cartesian observerPositionFixed,
                                                                           @Nonnull
                                                                           Cartesian targetPositionFixed,
                                                                           @Nonnull
                                                                           TerrainProvider terrainProvider)

Computes the point on terrain with the highest elevation angle between the observer and target positions from the perspective of the position closest to the Shape (get / set). The TerrainAlongLine.DefaultMinimumTerrainHeight and TerrainAlongLine.DefaultMaximumTerrainHeight are used for the computation.

Parameters:

observerPositionFixed - The position of the observer object, expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

targetPositionFixed - The position of the target object, expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

Returns:

The point on terrain with the highest elevation angle between the observer and target positions from the perspective of the position closest to the Shape (get / set).

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computePositionWithMaximumElevationAngle

@Nonnull
public static Cartesian computePositionWithMaximumElevationAngle(@Nonnull
                                                                           Cartesian observerPositionFixed,
                                                                           @Nonnull
                                                                           Cartesian targetPositionFixed,
                                                                           @Nonnull
                                                                           TerrainProvider terrainProvider,
                                                                           double minimumTerrainHeight,
                                                                           double maximumTerrainHeight)

Computes the point on terrain with the highest elevation angle between the observer and target positions from the perspective of the position closest to the Shape (get / set).

Parameters:

observerPositionFixed - The position of the observer object, expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

targetPositionFixed - The position of the target object, expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMinimumTerrainHeight is a safe value to use for this parameter.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMaximumTerrainHeight is a safe value to use for this parameter.

Returns:

The point on terrain with the highest elevation angle between the observer and target positions from the perspective of the position closest to the Shape (get / set).

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computePositionWithMaximumElevationAngle

@Nonnull
public static Cartesian computePositionWithMaximumElevationAngle(@Nonnull
                                                                           Cartographic observerPosition,
                                                                           @Nonnull
                                                                           Cartographic targetPosition,
                                                                           @Nonnull
                                                                           TerrainProvider terrainProvider)

Computes the point on terrain with the highest elevation angle between the observer and target positions from the perspective of the position closest to the Shape (get / set). The TerrainAlongLine.DefaultMinimumTerrainHeight and TerrainAlongLine.DefaultMaximumTerrainHeight are used for the computation.

Parameters:

observerPosition - The planetodetic position of the observer object, expressed as a longitude, latitude, and altitude relative to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

targetPosition - The planetodetic position of the target object, expressed as a longitude, latitude, and altitude relative to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

Returns:

The point on terrain with the highest elevation angle between the observer and target positions from the perspective of the position closest to the Shape (get / set).

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computePositionWithMaximumElevationAngle

@Nonnull
public static Cartesian computePositionWithMaximumElevationAngle(@Nonnull
                                                                           Cartographic observerPosition,
                                                                           @Nonnull
                                                                           Cartographic targetPosition,
                                                                           @Nonnull
                                                                           TerrainProvider terrainProvider,
                                                                           double minimumTerrainHeight,
                                                                           double maximumTerrainHeight)

Computes the point on terrain with the highest elevation angle between the observer and target positions from the perspective of the position closest to the Shape (get / set).

Parameters:

observerPosition - The planetodetic position of the observer object, expressed as a longitude, latitude, and altitude relative to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

targetPosition - The planetodetic position of the target object, expressed as a longitude, latitude, and altitude relative to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMinimumTerrainHeight is a safe value to use for this parameter.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMaximumTerrainHeight is a safe value to use for this parameter.

Returns:

The point on terrain with the highest elevation angle between the observer and target positions from the perspective of the position closest to the Shape (get / set).

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeElevationAngleAboveTerrain

public static double computeElevationAngleAboveTerrain(@Nonnull
                                                       Cartesian observerPositionFixed,
                                                       @Nonnull
                                                       Cartesian targetPositionFixed,
                                                       @Nonnull
                                                       TerrainProvider terrainProvider)

Computes the angle from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The angle is determined from the perspective of the position closest to the Shape (get / set). The TerrainAlongLine.DefaultMinimumTerrainHeight and TerrainAlongLine.DefaultMaximumTerrainHeight are used for the computation.

Parameters:

observerPositionFixed - The position of the observer object, expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

targetPositionFixed - The position of the target object, expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

Returns:

The angle from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The angle is determined from the perspective of the position closest to the Shape (get / set). Positive numbers indicate that the line of sight between the objects is not obscured by terrain. Negative numbers indicate that it is obscured.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeElevationAngleAboveTerrain

public static double computeElevationAngleAboveTerrain(@Nonnull
                                                       Cartesian observerPositionFixed,
                                                       @Nonnull
                                                       Cartesian targetPositionFixed,
                                                       @Nonnull
                                                       TerrainProvider terrainProvider,
                                                       double minimumTerrainHeight,
                                                       double maximumTerrainHeight)

Computes the angle from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The angle is determined from the perspective of the position closest to the Shape (get / set).

Parameters:

observerPositionFixed - The position of the observer object, expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

targetPositionFixed - The position of the target object, expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMinimumTerrainHeight is a safe value to use for this parameter.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMaximumTerrainHeight is a safe value to use for this parameter.

Returns:

The angle from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The angle is determined from the perspective of the position closest to the Shape (get / set). Positive numbers indicate that the line of sight between the objects is not obscured by terrain. Negative numbers indicate that it is obscured.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeElevationAngleAboveTerrain

public static double computeElevationAngleAboveTerrain(@Nonnull
                                                       Cartographic observerPosition,
                                                       @Nonnull
                                                       Cartographic targetPosition,
                                                       @Nonnull
                                                       TerrainProvider terrainProvider)

Computes the angle from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The angle is determined from the perspective of the position closest to the Shape (get / set). The TerrainAlongLine.DefaultMinimumTerrainHeight and TerrainAlongLine.DefaultMaximumTerrainHeight are used for the computation.

Parameters:

observerPosition - The planetodetic position of the observer object, expressed as a longitude, latitude, and altitude relative to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

targetPosition - The planetodetic position of the target object, expressed as a longitude, latitude, and altitude relative to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

Returns:

The angle from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The angle is determined from the perspective of the position closest to the Shape (get / set). Positive numbers indicate that the line of sight between the objects is not obscured by terrain. Negative numbers indicate that it is obscured.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeElevationAngleAboveTerrain

public static double computeElevationAngleAboveTerrain(@Nonnull
                                                       Cartographic observerPosition,
                                                       @Nonnull
                                                       Cartographic targetPosition,
                                                       @Nonnull
                                                       TerrainProvider terrainProvider,
                                                       double minimumTerrainHeight,
                                                       double maximumTerrainHeight)

Computes the angle from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The angle is determined from the perspective of the position closest to the Shape (get / set).

Parameters:

observerPosition - The planetodetic position of the observer object, expressed as a longitude, latitude, and altitude relative to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

targetPosition - The planetodetic position of the target object, expressed as a longitude, latitude, and altitude relative to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMinimumTerrainHeight is a safe value to use for this parameter.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMaximumTerrainHeight is a safe value to use for this parameter.

Returns:

The angle from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The angle is determined from the perspective of the position closest to the Shape (get / set). Positive numbers indicate that the line of sight between the objects is not obscured by terrain. Negative numbers indicate that it is obscured.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeObstructionMetric

public static double computeObstructionMetric(@Nonnull
                                              Cartesian observerPositionFixed,
                                              @Nonnull
                                              Cartesian targetPositionFixed,
                                              @Nonnull
                                              TerrainProvider terrainProvider,
                                              boolean findWorstObstruction,
                                              boolean findIndicatedExtremaPrecisely)

Computes a metric value indicating the amount of obstruction from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The metric value is determined from the perspective of the position closest to the Shape (get / set). The TerrainAlongLine.DefaultMinimumTerrainHeight and TerrainAlongLine.DefaultMaximumTerrainHeight are used for the computation.

Parameters:

observerPositionFixed - The position of the observer object, expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

targetPositionFixed - The position of the target object, expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

findWorstObstruction - Indicates whether the metric value associated with the worst amount of obstruction is sought.

findIndicatedExtremaPrecisely - Determines whether all extrema indicated from sampling should be found precisely.

Returns:

The metric value indicating obstruction from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The metric value is determined from the perspective of the position closest to the Shape (get / set). Positive numbers indicate that the line of sight between the objects is not obscured by terrain. Negative numbers indicate that it is obscured.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeObstructionMetric

public static double computeObstructionMetric(@Nonnull
                                              Cartesian observerPositionFixed,
                                              @Nonnull
                                              Cartesian targetPositionFixed,
                                              @Nonnull
                                              TerrainProvider terrainProvider,
                                              double minimumTerrainHeight,
                                              double maximumTerrainHeight,
                                              boolean findWorstObstruction,
                                              boolean findIndicatedExtremaPrecisely)

Computes a metric value indicating the amount of obstruction from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The metric value is determined from the perspective of the position closest to the Shape (get / set).

Parameters:

observerPositionFixed - The position of the observer object, expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

targetPositionFixed - The position of the target object, expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMinimumTerrainHeight is a safe value to use for this parameter.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMaximumTerrainHeight is a safe value to use for this parameter.

findWorstObstruction - Indicates whether the metric value associated with the worst amount of obstruction is sought.

findIndicatedExtremaPrecisely - Determines whether all extrema indicated from sampling should be found precisely.

Returns:

The metric value indicating obstruction from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The metric value is determined from the perspective of the position closest to the Shape (get / set). Positive numbers indicate that the line of sight between the objects is not obscured by terrain. Negative numbers indicate that it is obscured.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeObstructionMetric

public static double computeObstructionMetric(@Nonnull
                                              Cartographic observerPosition,
                                              @Nonnull
                                              Cartographic targetPosition,
                                              @Nonnull
                                              TerrainProvider terrainProvider,
                                              boolean findWorstObstruction,
                                              boolean findIndicatedExtremaPrecisely)

Computes a metric value indicating the amount of obstruction from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The metric value is determined from the perspective of the position closest to the Shape (get / set). The TerrainAlongLine.DefaultMinimumTerrainHeight and TerrainAlongLine.DefaultMaximumTerrainHeight are used for the computation.

Parameters:

observerPosition - The planetodetic position of the observer object, expressed as a longitude, latitude, and altitude relative to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

targetPosition - The planetodetic position of the target object, expressed as a longitude, latitude, and altitude relative to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

findWorstObstruction - Indicates whether the metric value associated with the worst amount of obstruction is sought.

findIndicatedExtremaPrecisely - Determines whether all extrema indicated from sampling should be found precisely.

Returns:

The metric value indicating obstruction from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The metric value is determined from the perspective of the position closest to the Shape (get / set). Positive numbers indicate that the line of sight between the objects is not obscured by terrain. Negative numbers indicate that it is obscured.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeObstructionMetric

public static double computeObstructionMetric(@Nonnull
                                              Cartographic observerPosition,
                                              @Nonnull
                                              Cartographic targetPosition,
                                              @Nonnull
                                              TerrainProvider terrainProvider,
                                              double minimumTerrainHeight,
                                              double maximumTerrainHeight,
                                              boolean findWorstObstruction,
                                              boolean findIndicatedExtremaPrecisely)

Computes a metric value indicating the amount of obstruction from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The metric value is determined from the perspective of the position closest to the Shape (get / set).

Parameters:

observerPosition - The planetodetic position of the observer object, expressed as a longitude, latitude, and altitude relative to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

targetPosition - The planetodetic position of the target object, expressed as a longitude, latitude, and altitude relative to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMinimumTerrainHeight is a safe value to use for this parameter.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMaximumTerrainHeight is a safe value to use for this parameter.

findWorstObstruction - Indicates whether the metric value associated with the worst amount of obstruction is sought.

findIndicatedExtremaPrecisely - Determines whether all extrema indicated from sampling should be found precisely.

Returns:

The metric value indicating obstruction from the line of sight between the target and observer positions and the direction to the point on terrain with the highest elevation angle. The metric value is determined from the perspective of the position closest to the Shape (get / set). Positive numbers indicate that the line of sight between the objects is not obscured by terrain. Negative numbers indicate that it is obscured.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeTerrainIntersection

@Nullable
public static Cartographic computeTerrainIntersection(@Nonnull
                                                                 Cartesian cartesian,
                                                                 @Nonnull
                                                                 UnitCartesian direction,
                                                                 double granularity,
                                                                 double maximumDistance,
                                                                 @Nonnull
                                                                 TerrainProvider terrainProvider)

Computes the location of the first intersection with terrain from the provided location along the indicated direction. The TerrainAlongLine.DefaultMinimumTerrainHeight and TerrainAlongLine.DefaultMaximumTerrainHeight are used for the computation.

Parameters:

cartesian - The Cartesian representation of the location expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

direction - The direction along which to check for intersection with terrain.

granularity - The sampling step as a positively valued fraction of the terrain resolution.

maximumDistance - A positively valued limit on the distance in meters along the indicated direction at which intersection with terrain is no longer checked.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

Returns:

The planetodetic location of intersection with terrain expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider or null if no intersection exists. The provided location may be returned as the point of intersection if it lies on the terrain surface and the indicated direction is directly into the terrain surface.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeTerrainIntersection

@Nullable
public static Cartographic computeTerrainIntersection(@Nonnull
                                                                 Cartesian cartesian,
                                                                 @Nonnull
                                                                 UnitCartesian direction,
                                                                 double granularity,
                                                                 double maximumDistance,
                                                                 @Nonnull
                                                                 TerrainProvider terrainProvider,
                                                                 double minimumTerrainHeight,
                                                                 double maximumTerrainHeight)

Computes the location of the first intersection with terrain from the provided location along the indicated direction.

Parameters:

cartesian - The Cartesian representation of the location expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

direction - The direction along which to check for intersection with terrain.

granularity - The sampling step as a positively valued fraction of the terrain resolution.

maximumDistance - A positively valued limit on the distance in meters along the indicated direction at which intersection with terrain is no longer checked.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMinimumTerrainHeight is a safe value to use for this parameter.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMaximumTerrainHeight is a safe value to use for this parameter.

Returns:

The planetodetic location of intersection with terrain expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider or null if no intersection exists. The provided location may be returned as the point of intersection if it lies on the terrain surface and the indicated direction is directly into the terrain surface.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeTerrainIntersection

@Nullable
public static Cartographic computeTerrainIntersection(@Nonnull
                                                                 Cartographic cartographic,
                                                                 @Nonnull
                                                                 UnitCartesian direction,
                                                                 double granularity,
                                                                 double maximumDistance,
                                                                 @Nonnull
                                                                 TerrainProvider terrainProvider)

Computes the location of the first intersection with terrain from the provided location along the indicated direction. The TerrainAlongLine.DefaultMinimumTerrainHeight and TerrainAlongLine.DefaultMaximumTerrainHeight are used for the computation.

Parameters:

cartographic - The planetodetic cartographic representation of the location expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

direction - The direction along which to check for intersection with terrain.

granularity - The sampling step as a positively valued fraction of the terrain resolution.

maximumDistance - A positively valued limit on the distance in meters along the indicated direction at which intersection with terrain is no longer checked.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

Returns:

The planetodetic location of intersection with terrain expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider or null if no intersection exists. The provided location may be returned as the point of intersection if it lies on the terrain surface and the indicated direction is directly into the terrain surface.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeTerrainIntersection

@Nullable
public static Cartographic computeTerrainIntersection(@Nonnull
                                                                 Cartographic cartographic,
                                                                 @Nonnull
                                                                 UnitCartesian direction,
                                                                 double granularity,
                                                                 double maximumDistance,
                                                                 @Nonnull
                                                                 TerrainProvider terrainProvider,
                                                                 double minimumTerrainHeight,
                                                                 double maximumTerrainHeight)

Computes the location of the first intersection with terrain from the provided location along the indicated direction.

Parameters:

cartographic - The planetodetic cartographic representation of the location expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

direction - The direction along which to check for intersection with terrain.

granularity - The sampling step as a positively valued fraction of the terrain resolution.

maximumDistance - A positively valued limit on the distance in meters along the indicated direction at which intersection with terrain is no longer checked.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMinimumTerrainHeight is a safe value to use for this parameter.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMaximumTerrainHeight is a safe value to use for this parameter.

Returns:

The planetodetic location of intersection with terrain expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider or null if no intersection exists. The provided location may be returned as the point of intersection if it lies on the terrain surface and the indicated direction is directly into the terrain surface.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeTerrainIntersection

@Nullable
public static Cartographic computeTerrainIntersection(@Nonnull
                                                                 Cartesian cartesian,
                                                                 @Nonnull
                                                                 Cartographic cartographic,
                                                                 @Nonnull
                                                                 UnitCartesian direction,
                                                                 double granularity,
                                                                 double maximumDistance,
                                                                 @Nonnull
                                                                 TerrainProvider terrainProvider)

Computes the location of the first intersection with terrain from the provided location along the indicated direction. Both Cartesian and Cartographic representations of the location are provided which eliminates the need for conversion within the algorithm and results in greater efficiency. The TerrainAlongLine.DefaultMinimumTerrainHeight and TerrainAlongLine.DefaultMaximumTerrainHeight are used for the computation.

Parameters:

cartesian - The Cartesian representation of the location expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

cartographic - The planetodetic cartographic representation of the location expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

direction - The direction along which to check for intersection with terrain.

granularity - The sampling step as a positively valued fraction of the terrain resolution.

maximumDistance - A positively valued limit on the distance in meters along the indicated direction at which intersection with terrain is no longer checked.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

Returns:

The planetodetic location of intersection with terrain expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider or null if no intersection exists. The provided location may be returned as the point of intersection if it lies on the terrain surface and the indicated direction is directly into the terrain surface.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.

computeTerrainIntersection

@Nullable
public static Cartographic computeTerrainIntersection(@Nonnull
                                                                 Cartesian cartesian,
                                                                 @Nonnull
                                                                 Cartographic cartographic,
                                                                 @Nonnull
                                                                 UnitCartesian direction,
                                                                 double granularity,
                                                                 double maximumDistance,
                                                                 @Nonnull
                                                                 TerrainProvider terrainProvider,
                                                                 double minimumTerrainHeight,
                                                                 double maximumTerrainHeight)

Computes the location of the first intersection with terrain from the provided location along the indicated direction. Both Cartesian and Cartographic representations of the location are provided which eliminates the need for conversion within the algorithm and results in greater efficiency.

Parameters:

cartesian - The Cartesian representation of the location expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

cartographic - The planetodetic cartographic representation of the location expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider.

direction - The direction along which to check for intersection with terrain.

granularity - The sampling step as a positively valued fraction of the terrain resolution.

maximumDistance - A positively valued limit on the distance in meters along the indicated direction at which intersection with terrain is no longer checked.

terrainProvider - The terrain provider describing the terrain that is potentially obscuring the path between the two objects.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMinimumTerrainHeight is a safe value to use for this parameter.

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. For realistic Earth-based terrain data, TerrainAlongLine.DefaultMaximumTerrainHeight is a safe value to use for this parameter.

Returns:

The planetodetic location of intersection with terrain expressed in the reference frame fixed to the ellipsoid specified by the Shape (get / set) property of the terrainProvider or null if no intersection exists. The provided location may be returned as the point of intersection if it lies on the terrain surface and the indicated direction is directly into the terrain surface.

Throws:

ArgumentNullException - Thrown if terrainProvider is null.