HiRISE

HiRISE.HiPlan.HiTemp
Class Observation_Timeline

java.lang.Object
  extended by HiRISE.HiPlan.HiTemp.Observation_Timeline

public class Observation_Timeline
extends Object

A timeline of HiRISE Observation_Events. Observation events may be added to and removed from the timeline by name, which is typically the observation's Observation_ID, although it is not required to be so. Whenever an observation event is added, the timeline is sorted accord to the natural sort order of the events, which is the start time. The timeline's units are assumed to be seconds.

The isPowerOn(double) boolean method may be used to determine whether HiRISE is powered on at a given time. The toXySeries() method may be used to create a JFreeChart XYSeries suitable for plotting in a JFreeChart.

Modeling HiRISE Behavior

HiRISE uses a first-in, first-out command queue to operate. Nearly all HiRISE commands go through this queue, including every command used in the acquisition of a HiRISE observation. This queue makes it impossible for the HiRISE system itself to ensure that an observation started at time t really takes place at time t. If some other commands are still running on the system, the observation will be bumped along in time until its commands reach the front of the queue.

Thus, if a 45-second observation is scheduled for 15:00:00 UTC and another 45-second observation is scheduled for 15:00:30 UTC, the second observation will actually start at 15:00:45 UTC instead of 15:00:30 UTC as commanded.

It is normally up to the planning software (for normal observations) and the JPL flight engineering team (FET) and the HiRISE engineering support team (HiEST) (for special operations) to ensure that two observations do not overlap. Observation_Timeline does not check to make sure such a conflict does not arise.

A future release of Observation_Timeline will model the HiRISE behavior correctly when there are overlapping observations; at the moment, however, it does not. Overlapping observations are modeled as a union of their start times and durations. In the example above, HiRISE would be modeled as being powered up from 15:00:00 UTC to 15:01:15 UTC, instead of from 15:00:00 UTC to 15:01:30 UTC.

Version:
1.19
Author:
Christian Schaller - UA/PIRL

Nested Class Summary
static class Observation_Timeline.TimeFormat
          Indicates the output format for the timeline.
 
Field Summary
static Pattern EPOCH_PATTERN
           
static String EPOCH_REGEX
           
static String ID
          Class identification name with source code version and date.
static Pattern STATE_FILE_PATTERN
           
static String STATE_FILE_REGEX
           
 
Constructor Summary
Observation_Timeline()
          Creates an empty Observation_Timeline object.
 
Method Summary
 void addObservation(Observation_Event event)
          Adds an observation event to the timeline.
 void addObservation(String identifier, double startTime, double duration)
          Adds an observation event to the timeline.
 boolean contains(String identifier)
          Tests if the named observation is included in this timeline.
 void exportToFile(File file)
           
 void exportToFile(File file, Observation_Timeline.TimeFormat format, String stateFilename)
          Exports the timeline to a given file with a given format for the start time.
 double getAutoDuration()
          Gets a nice duration for the timeline.
 double getDuration()
          Gets the duration of the timeline.
 int getIndexForDate(Date date)
          Gets the row index of the the observation whose start time is nearest to, but not greater than, the indicated date.
 Observation_Event getObservationEvent(String id)
          Gets the observation event with the indicated ID.
 List<String> getObservationIds(boolean includeArbitrary)
          Gets the current set of observation IDs in this timeline.
 List<Observation_Event> getObservations()
          Gets a list of observation events contained in this timeline.
 int getSize()
          Gets the number of Observation_Events in this timeline.
 double getStartTime()
          Gets the start time of the timeline.
 double getStopTime()
          Gets the stop time of the timeline.
 boolean isPowerOn(double time)
          Tests if HiRISE is powered on at a given time.
 void removeObservation(String identifier)
          Removes an observation from the timeline.
 XYSeries toXySeries()
          Creates an XYSeries from this timeline.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ID

public static final String ID
Class identification name with source code version and date.

See Also:
Constant Field Values

EPOCH_REGEX

public static final String EPOCH_REGEX
See Also:
Constant Field Values

STATE_FILE_REGEX

public static final String STATE_FILE_REGEX
See Also:
Constant Field Values

EPOCH_PATTERN

public static final Pattern EPOCH_PATTERN

STATE_FILE_PATTERN

public static final Pattern STATE_FILE_PATTERN
Constructor Detail

Observation_Timeline

public Observation_Timeline()
Creates an empty Observation_Timeline object.

Method Detail

getObservations

public List<Observation_Event> getObservations()
Gets a list of observation events contained in this timeline.

Returns:
a list of events.

getObservationEvent

public Observation_Event getObservationEvent(String id)
Gets the observation event with the indicated ID. If no such observation event exists, or if the ID is null or the empty string, a null is returned instead.

Parameters:
id - the observation ID in question.
Returns:
the event or null if the ID doesn't exist.

getSize

public int getSize()
Gets the number of Observation_Events in this timeline.

Returns:
the number of events in the timeline.

getObservationIds

public List<String> getObservationIds(boolean includeArbitrary)
Gets the current set of observation IDs in this timeline. If includeArbitrary is true, all observation IDs will be returned, including those for so-called arbitrary observations, i.e., those that are presumed not to be represented in the database. If false, the arbitrary observations will not be included.

Parameters:
includeArbitrary - if true, all arbitrary observations are included; otherwise they are not.
Returns:
the observation IDs.

getStartTime

public double getStartTime()
Gets the start time of the timeline. The start time is the start time of the earliest observation; if the timeline is empty, it is 0.0.

Returns:
the start time of the timeline in seconds.

getStopTime

public double getStopTime()
Gets the stop time of the timeline. The stop time is the start time of the last observation plus its duration; if the timeline is empty, it is 0.0.

Returns:
the stop time of the timeline in seconds.

getDuration

public double getDuration()
Gets the duration of the timeline. The duration is the stop time minus the start time; if the timeline is empty, it is 0.0.

Returns:
the duration of the timeline in seconds.

getAutoDuration

public double getAutoDuration()
Gets a nice duration for the timeline. The duration is getDuration(), rounded to the nearest hour, plus an additional 6 hours. This value is used for the auto-duration calculations in HiTemp and HiTemp_Batch.

Returns:
the auto-duration.

getIndexForDate

public int getIndexForDate(Date date)
Gets the row index of the the observation whose start time is nearest to, but not greater than, the indicated date. If the timeline is empty, or if the date is earlier than the earliest observation, this method returns a -1.

Parameters:
date - the date of interest.
Returns:
the row index of the matching observation, or -1 if none is found.

addObservation

public void addObservation(Observation_Event event)
Adds an observation event to the timeline. If the event already exists in the timeline, as determined by its Observation_Event.getIdentifier(), it is replaced by the new one.

The timeline is sorted by its natural order when the event is added. The natural sorting order for an Observation_Event is its Observation_Event.getStartTime().

Parameters:
event - the Observation_Event to be added.

addObservation

public void addObservation(String identifier,
                           double startTime,
                           double duration)
Adds an observation event to the timeline. If an event with the same identifier already exists in the timeline, it is replaced by the new one.

The timeline is sorted by its natural order when the event is added. The natural sorting order for an Observation_Event is its Observation_Event.getStartTime().

Parameters:
identifier - the unique ID of the new observation. Typically this identifier will be the string form of the observation ID associated with this observation, but it is not required to be so.
startTime - the start time of the new observation.
duration - the duration of the new observation.

removeObservation

public void removeObservation(String identifier)
Removes an observation from the timeline.

Parameters:
identifier - the unique identifier of the observation to remove.

contains

public boolean contains(String identifier)
Tests if the named observation is included in this timeline.

Parameters:
identifier - the unique ID of the observation.
Returns:
true if the observation is in the timeline, false otherwise.

isPowerOn

public boolean isPowerOn(double time)
Tests if HiRISE is powered on at a given time.

WARNING: This test does not correctly model HiRISE behavior as of this release. See the note in the class introduction.

Parameters:
time - the time at which the power status is to be tested.
Returns:
true if HiRISE is on at the given time, false otherwise.

toXySeries

public XYSeries toXySeries()
Creates an XYSeries from this timeline. This series is suitable for plotting in a JFreeChart.

The x-axis is time, sampled at 1.0-second intervals for the duration of the timeline plus 10.0 seconds. The y-axis is the instrument power state, ranging from 0.0 for "off" to 1.0 for "on."

Returns:
an XYSeries.

exportToFile

public void exportToFile(File file,
                         Observation_Timeline.TimeFormat format,
                         String stateFilename)
                  throws FileNotFoundException
Exports the timeline to a given file with a given format for the start time.

With the exception of the ET format, the various time formats have external dependencies into which this method has no direct visibility. For example, the Observation_Timeline.TimeFormat.ORBIT format requires that a state file be loaded into the static MTT layer via some external mechanism. If this method is unable to produce a start time in the desired format, it falls back to ET.

Parameters:
file - the filename; if null, data are written to System.out.
format - the start time format.
stateFilename - the state filename; may be null.
Throws:
FileNotFoundException

exportToFile

public void exportToFile(File file)
                  throws FileNotFoundException
Parameters:
file - the filename; if null, data are written to System.out.
Throws:
FileNotFoundException

HiRISE

Copyright (C) Arizona Board of Regents on behalf of the Planetary Image Research Laboratory, Lunar and Planetary Laboratory at the University of Arizona