org.orekit.rugged.api

Class RuggedBuilder

java.lang.Object

org.orekit.rugged.api.RuggedBuilder

public class RuggedBuilder
extends Object

Builder for Rugged instances.

This class implements the builder pattern to create Rugged instances. It does so by using a fluent API in order to clarify reading and allow later extensions with new configuration parameters.

A typical use would be:

   Rugged rugged = new RuggedBuilder().
                   setEllipsoid(EllipsoidId.WGS84, BodyRotatingFrameId.ITRF).
                   setAlgorithmID(AlgorithmId.Duvenhage).
                   setDigitalElevationModel(tileUpdater, maxCachedTiles).
                   setTimeSpan(minDate, maxDate, tStep, overshootTolerance).
                   setTrajectory(positionsVelocities, pvInterpolationNumber, pvFilter,
                                 quaternions, aInterpolationNumber, aFilter).
                   addLineSensor(sensor1).
                   addLineSensor(sensor2).
                   addLineSensor(sensor3).
                   build();
 

If a configuration parameter has not been set prior to the call to {]link #build()}, then an exception will be triggered with an explicit error message.

Author:

Luc Maisonobe

See Also:

Builder pattern (wikipedia), Fluent interface (wikipedia)

Constructor Summary

Constructors

Constructor and Description
RuggedBuilder() Create a non-configured builder.

Method Summary

Methods

Modifier and Type	Method and Description
RuggedBuilder	addLineSensor(LineSensor lineSensor) Set up line sensor model.
Rugged	build() Build a Rugged instance.
RuggedBuilder	clearLineSensors() Remove all line sensors.
boolean	getAberrationOfLightCorrection() Get the aberration of light correction flag.
AngularDerivativesFilter	getAFilter() Get the filter for derivatives from the sample to use in attitude interpolation.
int	getAInterpolationNumber() Get the number of points to use for attitude interpolation.
AlgorithmId	getAlgorithm() Get the algorithm to use for Digital Elevation Model intersection.
double	getConstantElevation() Get the constant elevation over ellipsoid to use with AlgorithmId.CONSTANT_ELEVATION_OVER_ELLIPSOID.
ExtendedEllipsoid	getEllipsoid() Get the ellipsoid.
Frame	getInertialFrame() Get the inertial frame.
boolean	getLightTimeCorrection() Get the light time correction flag.
List<LineSensor>	getLineSensors() Get all line sensors.
int	getMaxCachedTiles() Get the maximum number of tiles stored in the cache.
AbsoluteDate	getMaxDate() Get the end of search time span.
AbsoluteDate	getMinDate() Get the start of search time span.
double	getOvershootTolerance() Get the tolerance in seconds allowed for getMinDate() and getMaxDate() overshooting.
List<TimeStampedPVCoordinates>	getpositionsVelocities() Get the satellite position and velocity (m and m/s in inertial frame).
CartesianDerivativesFilter	getPVFilter() Get the filter for derivatives from the sample to use in position/velocity interpolation.
int	getPVInterpolationNumber() Get the number of points to use for position/velocity interpolation.
List<TimeStampedAngularCoordinates>	getQuaternions() Get the satellite quaternions with respect to inertial frame.
TileUpdater	getTileUpdater() Get the updater used to load Digital Elevation Model tiles.
double	getTStep() Get the step to use for inertial frame to body frame transforms cache computations.
RuggedBuilder	setAberrationOfLightCorrection(boolean aberrationOfLightCorrection) Set flag for aberration of light correction.
RuggedBuilder	setAlgorithm(AlgorithmId algorithmID) Set the algorithm to use for Digital Elevation Model intersection.
RuggedBuilder	setConstantElevation(double constantElevation) Set the user-provided constant elevation model.
RuggedBuilder	setDigitalElevationModel(TileUpdater tileUpdater, int maxCachedTiles) Set the user-provided tile updater.
RuggedBuilder	setEllipsoid(EllipsoidId ellipsoidID, BodyRotatingFrameId bodyRotatingFrameID) Set the reference ellipsoid.
RuggedBuilder	setEllipsoid(OneAxisEllipsoid ellipsoid) Set the reference ellipsoid.
RuggedBuilder	setLightTimeCorrection(boolean lightTimeCorrection) Set flag for light time correction.
RuggedBuilder	setTimeSpan(AbsoluteDate minDate, AbsoluteDate maxDate, double tStep, double overshootTolerance) Set the time span to be covered for direct and inverse location calls.
RuggedBuilder	setTrajectory(double interpolationStep, int interpolationNumber, CartesianDerivativesFilter pvFilter, AngularDerivativesFilter aFilter, Propagator propagator) Set the spacecraft trajectory.
RuggedBuilder	setTrajectory(Frame inertialFrame, List<TimeStampedPVCoordinates> positionsVelocities, int pvInterpolationNumber, CartesianDerivativesFilter pvFilter, List<TimeStampedAngularCoordinates> quaternions, int aInterpolationNumber, AngularDerivativesFilter aFilter) Set the spacecraft trajectory.
RuggedBuilder	setTrajectory(InertialFrameId inertialFrame, List<TimeStampedPVCoordinates> positionsVelocities, int pvInterpolationNumber, CartesianDerivativesFilter pvFilter, List<TimeStampedAngularCoordinates> quaternions, int aInterpolationNumber, AngularDerivativesFilter aFilter) Set the spacecraft trajectory.
RuggedBuilder	setTrajectoryAndTimeSpan(InputStream storageStream) Set both the spacecraft trajectory and the time span.
void	storeInterpolator(OutputStream storageStream) Store frames transform interpolator.

Methods inherited from class java.lang.Object

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

Constructor Detail

RuggedBuilder

public RuggedBuilder()

Create a non-configured builder.

The builder must be configured before calling the build() method, otherwise an exception will be triggered at build time.

Method Detail

setEllipsoid

public RuggedBuilder setEllipsoid(EllipsoidId ellipsoidID,
                         BodyRotatingFrameId bodyRotatingFrameID)
                           throws RuggedException

Set the reference ellipsoid.

Parameters:

ellipsoidID - reference ellipsoid

bodyRotatingFrameID - body rotating frame identifier

Returns:

the builder instance

Throws:

RuggedException - if data needed for some frame cannot be loaded or if trajectory has been recovered from an earlier run and frames mismatch

See Also:

setEllipsoid(OneAxisEllipsoid), getEllipsoid()

setEllipsoid

public RuggedBuilder setEllipsoid(OneAxisEllipsoid ellipsoid)
                           throws RuggedException

Set the reference ellipsoid.

Parameters:

ellipsoid - reference ellipsoid

Returns:

the builder instance

Throws:

RuggedException - if trajectory has been recovered from an earlier run and frames mismatch

See Also:

setEllipsoid(EllipsoidId, BodyRotatingFrameId), getEllipsoid()

getEllipsoid

public ExtendedEllipsoid getEllipsoid()

Get the ellipsoid.

Returns:

the ellipsoid

See Also:

setEllipsoid(EllipsoidId, BodyRotatingFrameId), setEllipsoid(OneAxisEllipsoid)

setAlgorithm

public RuggedBuilder setAlgorithm(AlgorithmId algorithmID)

Set the algorithm to use for Digital Elevation Model intersection.

Note that some algorithms require specific other methods to be called too:

• DUVENHAGE, DUVENHAGE_FLAT_BODY and BASIC_SLOW_EXHAUSTIVE_SCAN_FOR_TESTS_ONLY all require setDigitalElevationModel to be called,
• CONSTANT_ELEVATION_OVER_ELLIPSOID requires setConstantElevation to be called,
• IGNORE_DEM_USE_ELLIPSOID does not require any methods tobe called.

Parameters:

algorithmID - identifier of algorithm to use for Digital Elevation Model intersection

Returns:

the builder instance

See Also:

setDigitalElevationModel(TileUpdater, int), getAlgorithm()

getAlgorithm

public AlgorithmId getAlgorithm()

Get the algorithm to use for Digital Elevation Model intersection.

Returns:

algorithm to use for Digital Elevation Model intersection

See Also:

setAlgorithm(AlgorithmId)

setDigitalElevationModel

public RuggedBuilder setDigitalElevationModel(TileUpdater tileUpdater,
                                     int maxCachedTiles)

Set the user-provided tile updater.

Note that when the algorithm specified in setAlgorithm(AlgorithmId) is either CONSTANT_ELEVATION_OVER_ELLIPSOID or IGNORE_DEM_USE_ELLIPSOID, then this method becomes irrelevant and can either be not called at all, or it can be called with an updater set to null. For all other algorithms, the updater must be properly configured.

Parameters:

tileUpdater - updater used to load Digital Elevation Model tiles

maxCachedTiles - maximum number of tiles stored in the cache

Returns:

the builder instance

See Also:

setAlgorithm(AlgorithmId), getTileUpdater(), getMaxCachedTiles()

getTileUpdater

public TileUpdater getTileUpdater()

Get the updater used to load Digital Elevation Model tiles.

Returns:

updater used to load Digital Elevation Model tiles

See Also:

setDigitalElevationModel(TileUpdater, int), getMaxCachedTiles()

setConstantElevation

public RuggedBuilder setConstantElevation(double constantElevation)

Set the user-provided constant elevation model.

Note that this method is relevant only if the algorithm specified in setAlgorithm(AlgorithmId) is CONSTANT_ELEVATION_OVER_ELLIPSOID. If it is called for another algorithm, the elevation set here will be ignored.

Parameters:

constantElevation - constant elevation to use

Returns:

the builder instance

See Also:

setAlgorithm(AlgorithmId), getConstantElevation()

getConstantElevation

public double getConstantElevation()

Get the constant elevation over ellipsoid to use with AlgorithmId.CONSTANT_ELEVATION_OVER_ELLIPSOID.

Returns:

updater used to load Digital Elevation Model tiles

See Also:

setConstantElevation(double)

getMaxCachedTiles

public int getMaxCachedTiles()

Get the maximum number of tiles stored in the cache.

Returns:

maximum number of tiles stored in the cache

See Also:

setDigitalElevationModel(TileUpdater, int), getTileUpdater()

setTimeSpan

public RuggedBuilder setTimeSpan(AbsoluteDate minDate,
                        AbsoluteDate maxDate,
                        double tStep,
                        double overshootTolerance)

Set the time span to be covered for direct and inverse location calls.

This method set only the time span and not the trajectory, therefore it must be used together with either setTrajectory(InertialFrameId, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter), setTrajectory(Frame, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter), or setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator) but should not be mixed with setTrajectoryAndTimeSpan(InputStream).

Parameters:

minDate - start of search time span

maxDate - end of search time span

tStep - step to use for inertial frame to body frame transforms cache computations

overshootTolerance - tolerance in seconds allowed for minDate and maxDate overshooting

Returns:

the builder instance

See Also:

setTrajectoryAndTimeSpan(InputStream), getMinDate(), getMaxDate(), getTStep(), getOvershootTolerance()

getMinDate

public AbsoluteDate getMinDate()

Get the start of search time span.

Returns:

start of search time span

See Also:

setTimeSpan(AbsoluteDate, AbsoluteDate, double, double)

getMaxDate

public AbsoluteDate getMaxDate()

Get the end of search time span.

Returns:

end of search time span

See Also:

setTimeSpan(AbsoluteDate, AbsoluteDate, double, double)

getTStep

public double getTStep()

Get the step to use for inertial frame to body frame transforms cache computations.

Returns:

step to use for inertial frame to body frame transforms cache computations

See Also:

setTimeSpan(AbsoluteDate, AbsoluteDate, double, double)

getOvershootTolerance

public double getOvershootTolerance()

Get the tolerance in seconds allowed for getMinDate() and getMaxDate() overshooting.

Returns:

tolerance in seconds allowed for getMinDate() and getMaxDate() overshooting

See Also:

setTimeSpan(AbsoluteDate, AbsoluteDate, double, double)

setTrajectory

public RuggedBuilder setTrajectory(InertialFrameId inertialFrame,
                          List<TimeStampedPVCoordinates> positionsVelocities,
                          int pvInterpolationNumber,
                          CartesianDerivativesFilter pvFilter,
                          List<TimeStampedAngularCoordinates> quaternions,
                          int aInterpolationNumber,
                          AngularDerivativesFilter aFilter)
                            throws RuggedException

Set the spacecraft trajectory.

This method set only the trajectory and not the time span, therefore it must be used together with the setTimeSpan(AbsoluteDate, AbsoluteDate, double, double) but should not be mixed with setTrajectoryAndTimeSpan(InputStream).

Parameters:

inertialFrame - inertial frame used for spacecraft positions/velocities/quaternions

positionsVelocities - satellite position and velocity (m and m/s in inertial frame)

pvInterpolationNumber - number of points to use for position/velocity interpolation

pvFilter - filter for derivatives from the sample to use in position/velocity interpolation

quaternions - satellite quaternions with respect to inertial frame

aInterpolationNumber - number of points to use for attitude interpolation

aFilter - filter for derivatives from the sample to use in attitude interpolation

Returns:

the builder instance

Throws:

RuggedException - if data needed for inertial frame cannot be loaded

See Also:

setTrajectory(Frame, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter), setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator), setTrajectoryAndTimeSpan(InputStream), getInertialFrame(), getpositionsVelocities(), getPVInterpolationNumber(), getPVInterpolationNumber(), getQuaternions(), getAInterpolationNumber(), getAFilter()

setTrajectory

public RuggedBuilder setTrajectory(Frame inertialFrame,
                          List<TimeStampedPVCoordinates> positionsVelocities,
                          int pvInterpolationNumber,
                          CartesianDerivativesFilter pvFilter,
                          List<TimeStampedAngularCoordinates> quaternions,
                          int aInterpolationNumber,
                          AngularDerivativesFilter aFilter)

Set the spacecraft trajectory.

This method set only the trajectory and not the time span, therefore it must be used together with the setTimeSpan(AbsoluteDate, AbsoluteDate, double, double) but should not be mixed with setTrajectoryAndTimeSpan(InputStream).

Parameters:

inertialFrame - inertial frame used for spacecraft positions/velocities/quaternions

positionsVelocities - satellite position and velocity (m and m/s in inertial frame)

pvInterpolationNumber - number of points to use for position/velocity interpolation

pvFilter - filter for derivatives from the sample to use in position/velocity interpolation

quaternions - satellite quaternions with respect to inertial frame

aInterpolationNumber - number of points to use for attitude interpolation

aFilter - filter for derivatives from the sample to use in attitude interpolation

Returns:

the builder instance

See Also:

setTrajectory(InertialFrameId, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter), setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator), setTrajectoryAndTimeSpan(InputStream), getpositionsVelocities(), getPVInterpolationNumber(), getPVInterpolationNumber(), getQuaternions(), getAInterpolationNumber(), getAFilter()

setTrajectory

public RuggedBuilder setTrajectory(double interpolationStep,
                          int interpolationNumber,
                          CartesianDerivativesFilter pvFilter,
                          AngularDerivativesFilter aFilter,
                          Propagator propagator)

Set the spacecraft trajectory.

This method set only the trajectory and not the time span, therefore it must be used together with the setTimeSpan(AbsoluteDate, AbsoluteDate, double, double) but should not be mixed with setTrajectoryAndTimeSpan(InputStream).

Parameters:

interpolationStep - step to use for inertial/Earth/spacraft transforms interpolations

interpolationNumber - number of points to use for inertial/Earth/spacraft transforms interpolations

pvFilter - filter for derivatives from the sample to use in position/velocity interpolation

aFilter - filter for derivatives from the sample to use in attitude interpolation

propagator - global propagator

Returns:

the builder instance

See Also:

setTrajectory(InertialFrameId, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter), setTrajectory(Frame, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter), setTrajectoryAndTimeSpan(InputStream)

getInertialFrame

public Frame getInertialFrame()

Get the inertial frame.

Returns:

inertial frame

getpositionsVelocities

public List<TimeStampedPVCoordinates> getpositionsVelocities()

Get the satellite position and velocity (m and m/s in inertial frame).

Returns:

satellite position and velocity (m and m/s in inertial frame)

See Also:

setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)

getPVInterpolationNumber

public int getPVInterpolationNumber()

Get the number of points to use for position/velocity interpolation.

Returns:

number of points to use for position/velocity interpolation

See Also:

setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)

getPVFilter

public CartesianDerivativesFilter getPVFilter()

Get the filter for derivatives from the sample to use in position/velocity interpolation.

Returns:

filter for derivatives from the sample to use in position/velocity interpolation

See Also:

setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)

getQuaternions

public List<TimeStampedAngularCoordinates> getQuaternions()

Get the satellite quaternions with respect to inertial frame.

Returns:

satellite quaternions with respect to inertial frame

See Also:

setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)

getAInterpolationNumber

public int getAInterpolationNumber()

Get the number of points to use for attitude interpolation.

Returns:

number of points to use for attitude interpolation

See Also:

setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)

getAFilter

public AngularDerivativesFilter getAFilter()

Get the filter for derivatives from the sample to use in attitude interpolation.

Returns:

filter for derivatives from the sample to use in attitude interpolation

See Also:

setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator)

setTrajectoryAndTimeSpan

public RuggedBuilder setTrajectoryAndTimeSpan(InputStream storageStream)
                                       throws RuggedException

Set both the spacecraft trajectory and the time span.

This method set both the trajectory and the time span in a tightly coupled way, therefore it should not be mixed with the individual methods setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator), setTrajectory(Frame, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter), setTrajectory(InertialFrameId, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter), or setTimeSpan(AbsoluteDate, AbsoluteDate, double, double).

Parameters:

storageStream - stream from where to read previous instance stored interpolator (caller opened it and remains responsible for closing it)

Returns:

the builder instance

Throws:

RuggedException - if storage stream cannot be parsed or if frames do not match the ones referenced in the storage stream

See Also:

setTrajectory(InertialFrameId, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter), setTrajectory(Frame, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter), setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator), storeInterpolator(OutputStream)

storeInterpolator

public void storeInterpolator(OutputStream storageStream)
                       throws RuggedException

Store frames transform interpolator.

This method allows to reuse the interpolator built in one instance, to build another instance by calling setTrajectoryAndTimeSpan(InputStream). This reduces the builder initialization time as setting up the interpolator can be long, it is mainly intended to be used when several runs are done (for example in an image processing chain) with the same configuration.

This method must be called after both the ellipsoid and trajectory have been set.

Parameters:

storageStream - stream where to store the interpolator (caller opened it and remains responsible for closing it)

Throws:

RuggedException - if interpolator cannot be written to stream

See Also:

setEllipsoid(EllipsoidId, BodyRotatingFrameId), setEllipsoid(OneAxisEllipsoid), setTrajectory(InertialFrameId, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter), setTrajectory(Frame, List, int, CartesianDerivativesFilter, List, int, AngularDerivativesFilter), setTrajectory(double, int, CartesianDerivativesFilter, AngularDerivativesFilter, Propagator), setTrajectoryAndTimeSpan(InputStream)

setLightTimeCorrection

public RuggedBuilder setLightTimeCorrection(boolean lightTimeCorrection)

Set flag for light time correction.

This methods set the flag for compensating or not light time between ground and spacecraft. Compensating this delay improves location accuracy and is enabled by default (i.e. not calling this method before building is therefore equivalent to calling it with a parameter set to true). Not compensating it is mainly useful for validation purposes against system that do not compensate it.

Parameters:

lightTimeCorrection - if true, the light travel time between ground and spacecraft is compensated for more accurate location

Returns:

the builder instance

See Also:

setAberrationOfLightCorrection(boolean), getLightTimeCorrection()

getLightTimeCorrection

public boolean getLightTimeCorrection()

Get the light time correction flag.

Returns:

light time correction flag

See Also:

setLightTimeCorrection(boolean)

setAberrationOfLightCorrection

public RuggedBuilder setAberrationOfLightCorrection(boolean aberrationOfLightCorrection)

Set flag for aberration of light correction.

This methods set the flag for compensating or not aberration of light, which is velocity composition between light and spacecraft when the light from ground points reaches the sensor. Compensating this velocity composition improves location accuracy and is enabled by default (i.e. not calling this method before building is therefore equivalent to calling it with a parameter set to true). Not compensating it is useful in two cases: for validation purposes against system that do not compensate it or when the pixels line of sight already include the correction.

Parameters:

aberrationOfLightCorrection - if true, the aberration of light is corrected for more accurate location

Returns:

the builder instance

See Also:

setLightTimeCorrection(boolean), getAberrationOfLightCorrection()

getAberrationOfLightCorrection

public boolean getAberrationOfLightCorrection()

Get the aberration of light correction flag.

Returns:

aberration of light correction flag

See Also:

setAberrationOfLightCorrection(boolean)

addLineSensor

public RuggedBuilder addLineSensor(LineSensor lineSensor)

Set up line sensor model.

Parameters:

lineSensor - line sensor model

Returns:

the builder instance

clearLineSensors

public RuggedBuilder clearLineSensors()

Remove all line sensors.

Returns:

the builder instance

getLineSensors

public List<LineSensor> getLineSensors()

Get all line sensors.

Returns:

all line sensors (in an unmodifiable list)

build

public Rugged build()
             throws RuggedException

Build a Rugged instance.

Returns:

built instance

Throws:

RuggedException - if the builder is not properly configured or if some internal elements cannot be built (frames, ephemerides, ...)