agi.foundation.routedesign.advanced

(agi.foundation.routedesign-2024r2.jar)

Class SurfaceSegment

java.lang.Object

agi.foundation.infrastructure.DefinitionalObject

agi.foundation.routedesign.advanced.SurfaceSegment

All Implemented Interfaces:

ICloneWithContext, IEnumerateDependencies, IEquatableDefinition, IFreezable

Direct Known Subclasses:

CompositeSurfaceSegment, DegenerateSurfaceSegment, PartialSurfaceSegment, SurfaceCurveSegment

public abstract class SurfaceSegment
extends DefinitionalObject

The base class for all types representing the immutable geometry of the surface path corresponding to all or part of a particular RouteSegment.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SurfaceSegment() Initializes a new instance.
protected	SurfaceSegment(Ellipsoid shape, double surfaceDistance) Create a new instance with the given surface shape and total distance.
protected	SurfaceSegment(SurfaceSegment otherInstance) Create a new instance based on an existing one.
protected	SurfaceSegment(SurfaceSegment 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(DefinitionalObject other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected abstract boolean	checkForSameDefinition(SurfaceSegment other) Checks to determine if another instance has the same definition as this instance and returns true if it does.
protected CartographicExtent	computeCartographicExtent() Computes the latitude and longitude boundary surrounding this segment.
protected int	computeCurrentDefinitionHashCode() Computes a hash code based on the current properties of this object.
EllipsoidSurfaceCurve	createSurfaceCurve() Create an EllipsoidSurfaceCurve which represents this segment of a route along the surface.
double	getFinalHeading() Gets the final heading measured eastward from north, in radians.
Cartographic	getFinalSurfacePoint() Gets the final position at the end of the surface segment.
double	getHeading(double distanceAlongPath) Get the heading measured clockwise from local north, in radians.
abstract Motion1<Double>	getHeading(Motion1<Double> distanceAlongPath, int order) Get the heading and its derivatives, in radians and radians/meter.
double	getInitialHeading() Gets the initial heading measured eastward from north, in radians.
Cartographic	getInitialSurfacePoint() Gets the initial position at the start of the surface segment.
double	getSurfaceDistance() Gets the total arc length along the surface path, in meters.
Ellipsoid	getSurfaceShape() Gets the shape of the surface upon which the path is defined.
abstract double[]	getTransitionPoints() Gets the arc lengths, in meters, at which the geometry changes behavior.
boolean	isSameDefinition(SurfaceSegment other) Determines if this object has the same definition as another object.
protected void	setSurfaceDistance(double value) Sets the total arc length along the surface path, in meters.
protected void	setSurfaceShape(Ellipsoid value) Sets the shape of the surface upon which the path is defined.
Cartesian	traverseFixed(double distanceAlongPath) Get the surface position in the fixed frame of the SurfaceShape (get / set) at the specified distance along the surface path.
abstract Cartographic	traverseSurface(double distanceAlongPath) Get the surface position at the specified distance along the surface path.

Methods inherited from class agi.foundation.infrastructure.DefinitionalObject

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

SurfaceSegment

protected SurfaceSegment()

Initializes a new instance.

SurfaceSegment

protected SurfaceSegment(Ellipsoid shape,
                         double surfaceDistance)

Create a new instance with the given surface shape and total distance.

Parameters:

shape - The shape of the surface upon which this segment is defined.

surfaceDistance - The total distance along the surface path, in meters.

SurfaceSegment

protected SurfaceSegment(@Nonnull
                         SurfaceSegment otherInstance)

Create a new instance based on an existing one.

Parameters:

otherInstance - The other instance to copy.

SurfaceSegment

protected SurfaceSegment(@Nonnull
                         SurfaceSegment 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(DefinitionalObject 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 DefinitionalObject

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(SurfaceSegment 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 SurfaceSegment.checkForSameDefinition(agi.foundation.infrastructure.DefinitionalObject) method.

Overrides:

computeCurrentDefinitionHashCode in class DefinitionalObject

Returns:

The computed hash code.

isSameDefinition

public final boolean isSameDefinition(SurfaceSegment other)

Determines if this object has the same definition as another object.

This method is very similar to Object.equals(Object) except that it explicitly considers the "definitions" of the two objects for objects that do not typically act like values. The definition of an object typically includes all of the fields of the object.

Parameters:

other - The other instance to compare to this one.

Returns:

true if this object has the same definition as the specified one. false if the other object is null, a different type than this one, or if this object and the specified one have different definitions.

traverseFixed

@Nonnull
public Cartesian traverseFixed(double distanceAlongPath)

Get the surface position in the fixed frame of the SurfaceShape (get / set) at the specified distance along the surface path.

Parameters:

distanceAlongPath - The distance along the path, in meters.

Returns:

The fixed surface position of the path at the specified distance.

traverseSurface

@Nonnull
public abstract Cartographic traverseSurface(double distanceAlongPath)

Get the surface position at the specified distance along the surface path.

Parameters:

distanceAlongPath - The distance along the surface path, in meters.

Returns:

The Cartographic position at the given distance along the path.

getHeading

public double getHeading(double distanceAlongPath)

Get the heading measured clockwise from local north, in radians.

Parameters:

distanceAlongPath - The distance along the surface path, in meters.

Returns:

The heading at the given position along the path.

getHeading

@Nonnull
public abstract Motion1<Double> getHeading(@Nonnull
                                                     Motion1<Double> distanceAlongPath,
                                                     int order)

Get the heading and its derivatives, in radians and radians/meter.

Note that the units for the derivatives here are in radians and meters. To get the time rates of change of heading, use the chain rule with the time rate of change of the arc length parameter.

Parameters:

distanceAlongPath - The distance along the surface path, in meters.

order - The requested order indicating the number of derivatives to compute.

Returns:

The heading and its derivatives, in radians and radians/meter.

getSurfaceShape

public final Ellipsoid getSurfaceShape()

Gets the shape of the surface upon which the path is defined.

setSurfaceShape

protected final void setSurfaceShape(Ellipsoid value)

Sets the shape of the surface upon which the path is defined.

getSurfaceDistance

public final double getSurfaceDistance()

Gets the total arc length along the surface path, in meters.

setSurfaceDistance

protected final void setSurfaceDistance(double value)

Sets the total arc length along the surface path, in meters.

getTransitionPoints

@Nonnull
public abstract double[] getTransitionPoints()

Gets the arc lengths, in meters, at which the geometry changes behavior. This could represent discontinuities in the route in one or more derivatives or other points of interest.

getInitialSurfacePoint

@Nonnull
public Cartographic getInitialSurfacePoint()

Gets the initial position at the start of the surface segment.

getFinalSurfacePoint

@Nonnull
public Cartographic getFinalSurfacePoint()

Gets the final position at the end of the surface segment.

getInitialHeading

public double getInitialHeading()

Gets the initial heading measured eastward from north, in radians.

getFinalHeading

public double getFinalHeading()

Gets the final heading measured eastward from north, in radians.

createSurfaceCurve

@Nonnull
public EllipsoidSurfaceCurve createSurfaceCurve()

Create an EllipsoidSurfaceCurve which represents this segment of a route along the surface.

Returns:

A surface curve representing this segment of the route along the surface.

computeCartographicExtent

@Nonnull
protected CartographicExtent computeCartographicExtent()

Computes the latitude and longitude boundary surrounding this segment.

Returns:

A CartographicExtent that bounds this surface segment.