HiRISE

HiRISE.libHiRISE
Class Observation_ID

java.lang.Object
  extended by HiRISE.libHiRISE.Observation_ID
Direct Known Subclasses:
CCD_ID

public class Observation_ID
extends Object

A data object that encapsulates the HiRISE observation identification number.

The ID is a 32-bit number that uniquely identifies every HiRISE observation, and it is carried along with the observation from the planning stage all the way through to the final released data product. The ID has two forms: a numeric, binary representation as an unsigned 32-bit integer and a text representation more easily parsed by a human. The latter form is used, for example, in HiRISE observation filenames.

Information about an observation is encoded in the Observation_ID as a set of bitfields, with a total of 32 bits per ID. We define the following: bit 0 is the bit that controls whether the integer is even or odd. If bit 0 of an integer is 0, then the integer is even. If bit 0 is 1, then the integer is odd. Bit 1 is the next bit, and so on.

There are two different interpretations of the Observation_ID's bitfields. The first is for pre-Mars orbit observations ("pre-orbit"). These observations are acquired during the period of time from initial integration and testing at the instrument's manufacturing facility to Mars approach and insertion. The second interpretation is for observations while the Mars Reconnaissance Orbiter (MRO) is in orbit around Mars, from initial aerobraking to the late-mission relay phase and beyond.

The two forms share the top five bits, which identify the mission phase for the observation. A set of integer constants is used to represent the phases. Most of the Mission_Phase values are reserved for future use. The following table outlines the various phases:

Mission_Phase Mission_Phase Text
INTEGRATION_AND_TESTING INT
CALIBRATION CAL
ATLO ATL
KENNEDY_SPACE_CENTER KSC
LAUNCH LAU
CRUISE CRU
APPROACH APR
AEROBRAKING AEB
TRANSITION TRA
PRIMARY_SCIENCE_PHASE PSP
RELAY REL
EXTENDED_SCIENCE_PHASE ESP
RESERVED_1 R01
RESERVED_2 R02
RESERVED_3 R03
RESERVED_4 R04
RESERVED_5 R05
RESERVED_6 R06
RESERVED_7 R07
RESERVED_8 R08
RESERVED_9 R09
RESERVED_10 R10
RESERVED_11 R11
RESERVED_12 R12
RESERVED_13 R13
RESERVED_14 R14
RESERVED_15 R15
RESERVED_16 R16
RESERVED_17 R17
RESERVED_18 R18
RESERVED_19 R19
SVT SVT

Pre-Orbit Representation

A pre-orbit Observation_ID has two fields: Mission_Phase and Time. These fields are broken down in the following table:

Bit Range Count Parameter
27-31 5 Mission_Phase
0-26 27 Time

The Time field holds the number of seconds that have passed since the HiRISE EPOCH, which is January 1, 2004, 00:00:00. Time is UTC-based.

The text representation for a pre-orbit Observation_ID is as follows:

PPP_yyyymmddTHHMMSS

In-Orbit Representation

An in-orbit Observation_ID has three fields: Mission_Phase, Orbit_Number, and Target. These fields are broken down in the following table:

Bit Range Count Parameter
27-31 5 Mission_Phase
10-26 17 Orbit_Number
0-9 10 Target

Orbit_Number begins at 0 with the first aerobraking orbit and continues to increase until end-of-mission.

Target identifies the target at which the instrument is pointed for a given observation. With 10 bits assigned to Target, there are 1024 possible Target numbers.

The text representation for an in-orbit Observation_ID is as follows:

PPP_NNNNNN_TTTT

The text representation of the Target number is defined as follows: Values between 0000 and 3595, inclusive, reflect the central latitude of the observation to within a half-degree, multiplied by 10. (0905, for example, is thus a latitude of 90.5 degrees.) 0.0 degrees is the night-side equator, which is where the orbit number increments. 90.0 south pole on the ascending pass. 180.0 is the day-side equator on the ascending pass. 270.0 is the north pole on the descending pass.

Text values between 9000 and 9303, inclusive, represent off-planet targets such as Phobos, Deimos, or stars.

Text versus Numeric Target Representation

For any numeric Target representation N (0...1023, inclusive), the text represenation T is defined as follows:

N T
0 <= N < 720 T = N x 5
720 <= N <= 1023 T = 8280 + N

The conversion is easily reversible, although T is discontinuous.

About the SVT Phase

The SVT phase is a special case mission phase. It is used to represent images taken during ATLO sequence verification tests (SVTs) that are designed to simulate in-orbit observation conditions. In all ways, the SVT phase is therefore treated as an in-orbit phase, although it will never actually be used while in orbit around Mars.

Differences Between Java and C++ Implementations

(...)

Version:
2.13
Author:
Christian Schaller - UA/PIRL, Michael Wendell - UA/PIRL

Field Summary
static int AEROBRAKING
          The aerobraking mission phase.
static int APPROACH
          The approach mission phase.
static int ATLO
          The assembly, test, and launch operations mission phase.
static int CALIBRATION
          The calibration mission phase.
protected static String CPMM_AND_CHANNEL_PATTERN
           
static int CRUISE
          The cruise mission phase.
static int DEFAULT_INORBIT_PHASE
          The default mission phase for in-orbit observations.
static int DEFAULT_MISSION_PHASE
          The default mission phase.
static int DEFAULT_OBSERVATION_ID
          The default Observation_ID value.
static int DEFAULT_ORBIT_NUMBER
          The default value for the Orbit_Number component of an in-orbit Observation_ID.
static int DEFAULT_PREORBIT_PHASE
          The default mission phase for pre-orbit observations.
static int DEFAULT_TARGET
          The default value for the Target component of an in-orbit Observation_ID.
static int DEFAULT_TIME
          The default value for the Time component of a pre-orbit Observation_ID.
static String DEFAULT_TIME_TEXT_FORMAT
          The default text format for the Time component of an Observation_ID.
protected static String DELIMITER_PATTERN
           
static int EPOCH
          Reference date for Observation_ID pre-orbit times.
static int EXTENDED_SCIENCE_PHASE
          The extended science mission phase.
static char EXTENSION_DELIMITER
          An extension delimiter used in parsing Observation_ID text.
protected static String EXTENSION_PATTERN
           
protected static String GAP_INDICATOR_PATTERN
           
static String ID
          Class identification name with source code version and date.
protected static int INORBIT_MISSION_PHASE_GROUP
           
protected static int INORBIT_ORBIT_NUMBER_GROUP
           
protected static int INORBIT_PREFIX_GROUP
           
protected static int INORBIT_SUFFIX_GROUP
           
protected static int INORBIT_TARGET_GROUP
           
protected static String INSTRUMENT_ID_PATTERN
           
static int INTEGRATION_AND_TESTING
          The integreation and testing mission phase.
static int INVALID_OBSERVATION_ID
          The invalid Observation_ID value.
static String JPL_TIME_TEXT_FORMAT
          The JPL format for the text representation of time.
static int KENNEDY_SPACE_CENTER
          The Kennedy Space Center mission phase.
static int LAST_PREORBIT_PHASE
          The last pre-orbit mission phase.
static int LAUNCH
          The launch mission phase.
static String[] MISSION_PHASE_ABBREVIATION
          The three-letter text representation of each mission phase, indexed by the 32 mission phase constants.
static int MISSION_PHASE_BIT_COUNT
          The number of bits used for the Mission_Phase component.
static int MISSION_PHASE_MASK
          The Mission_Phase bitmask.
static int MISSION_PHASE_MAX
          The maximum value of the Mission_Phase component.
static int[] MISSION_PHASE_MAX_ORBIT
          The orbit numbers associated with the mission phases.
static int[] MISSION_PHASE_MAX_TIME
          The times/dates associated with the mission phases.
static String[] MISSION_PHASE_NAME
          The full descriptive name of each mission phase, indexed by the 32 mission phase constants.
protected static String MISSION_PHASE_PATTERN
           
static int MISSION_PHASE_START
          The index of the first Mission_Phase bit.
protected static String OBSERVATION_ID_PATTERN
           
protected static String OPTIONAL_DELIMITER_PATTERN
           
static int ORBIT_NUMBER_BIT_COUNT
          The number of bits used for the Orbit_Number in-orbit component.
static int ORBIT_NUMBER_MASK
          The Orbit_Number in-orbit component bitmask.
static int ORBIT_NUMBER_MAX
          The maximum value of the Orbit_Number in-orbit component.
static int ORBIT_NUMBER_MIN
          The minimum value of the Orbit_Number in-orbit component.
protected static String ORBIT_NUMBER_PATTERN
           
static int ORBIT_NUMBER_START
          The index of the first Orbit_Number bit in an in-orbit ID.
static String PDS_TIME_TEXT_FORMAT
          The PDS format for the text representation of time.
protected static String PREFIX_PATTERN
           
protected static int PREORBIT_MISSION_PHASE_GROUP
           
protected static int PREORBIT_PREFIX_GROUP
           
protected static int PREORBIT_SUFFIX_GROUP
           
protected static int PREORBIT_TIME_GROUP
           
static int PRIMARY_SCIENCE_PHASE
          The primary science mission phase.
static int RELAY
          The telecommunications relay mission phase.
protected static String REQUIRED_DELIMITER_PATTERN
           
static int RESERVED_1
          A reserved mission phase.
static int RESERVED_10
          A reserved mission phase.
static int RESERVED_11
          A reserved mission phase.
static int RESERVED_12
          A reserved mission phase.
static int RESERVED_13
          A reserved mission phase.
static int RESERVED_14
          A reserved mission phase.
static int RESERVED_15
          A reserved mission phase.
static int RESERVED_16
          A reserved mission phase.
static int RESERVED_17
          A reserved mission phase.
static int RESERVED_18
          A reserved mission phase.
static int RESERVED_19
          A reserved mission phase.
static int RESERVED_2
          A reserved mission phase.
static int RESERVED_3
          A reserved mission phase.
static int RESERVED_4
          A reserved mission phase.
static int RESERVED_5
          A reserved mission phase.
static int RESERVED_6
          A reserved mission phase.
static int RESERVED_7
          A reserved mission phase.
static int RESERVED_8
          A reserved mission phase.
static int RESERVED_9
          A reserved mission phase.
protected static int RSDS_OPS_CPMM_AND_CHANNEL_GROUP
           
protected static int RSDS_OPS_EXTENSION_GROUP
           
protected static int RSDS_OPS_GAP_GROUP
           
protected static int RSDS_OPS_INSTRUMENT_ID_GROUP
           
protected static int RSDS_OPS_OBSERVATION_ID_GROUP
           
protected static int RSDS_OPS_SPACECRAFT_ID_GROUP
           
protected static int RSDS_OPS_VERSION_GROUP
           
protected static int RSDS_TEST_CPMM_AND_CHANNEL_GROUP
           
protected static int RSDS_TEST_EXTENSION_GROUP
           
protected static int RSDS_TEST_GAP_GROUP
           
protected static int RSDS_TEST_ID_GROUP
           
protected static int RSDS_TEST_INSTRUMENT_ID_GROUP
           
protected static int RSDS_TEST_OBSERVATION_ID_GROUP
           
protected static int RSDS_TEST_SPACECRAFT_ID_GROUP
           
protected static int RSDS_TEST_VERSION_GROUP
           
static String RSDS_TIME_TEXT_FORMAT
          The RSDS format for the text representation of time.
protected static String SPACECRAFT_ID_PATTERN
           
protected static String SUFFIX_PATTERN
           
static int SVT
          The sequence verification tests mission phase.
static int TARGET_BIT_COUNT
          The number of bits used for the Target in-orbit component.
static int TARGET_MASK
          The Target in-orbit component bitmask.
static int TARGET_MAX
          The maximum value of the Target in-orbit component.
protected static String TARGET_PATTERN
           
static int TARGET_START
          The index of the first Target bit in an in-orbit ID.
protected static String TEST_ID_PATTERN
           
static char TEXT_DELIMITER
          A text delimiter used in parsing Observation_ID text.
static int TIME_BIT_COUNT
          The number of bits used for the Time pre-orbit component.
static int TIME_MASK
          The Time pre-orbit component bitmask.
static int TIME_MAX
          The maximum value of the Time pre-orbit component.
protected static String TIME_PATTERN
           
static int TIME_START
          The index of the first Time bit in a pre-orbit ID.
static int TOTAL_MISSION_PHASES
          The total number of mission phases.
static int TRANSITION
          The transition mission phase.
protected static String VERSION_PATTERN
           
 
Constructor Summary
Observation_ID()
          Creates a default Observation_ID, whose value is DEFAULT_OBSERVATION_ID.
Observation_ID(int value)
          Creates an Observation_ID with the specified value.
Observation_ID(int the_mission_phase, int the_time)
          Creates a pre-orbit Observation_ID with the specified Mission_Phase and Time components.
Observation_ID(int the_mission_phase, int the_orbit_number, int the_target)
          Creates an in-orbit Observation_ID with the specified Mission_Phase, Orbit_Number, and Target components.
Observation_ID(String the_id_text)
          Creates an Observation_ID based on a text string.
 
Method Summary
static int extract_mission_phase(String the_text)
          Parses a Mission_Phase component from a text String.
static int extract_mission_phase(String the_text, boolean use_defaults)
          Parses a Mission_Phase component from a text String.
static int extract_orbit_number(String the_text)
          Parses an Orbit_Number in-orbit component from a text String.
static int extract_orbit_number(String the_text, boolean use_defaults)
          Parses an Orbit_Number in-orbit component from a text String.
static int extract_target(String the_text)
          Parses a Target in-orbit component from a text String.
static int extract_target(String the_text, boolean use_defaults)
          Parses a Target in-orbit component from a text String.
static int extract_time(String the_text)
          Parses a Time pre-orbit component from a text String.
static int extract_time(String the_text, boolean use_defaults)
          Parses a Time pre-orbit component from a text String.
 Observation_ID hex_value(String id_text)
          Sets this Observation_ID's numeric value using a string representing a hexidecimal 32-bit integer.
 Observation_ID hex_value(String id_text, boolean use_defaults)
          Sets this Observation_ID's numeric value using a string representing a hexadecimal 32-bit integer.
 boolean is_preorbit()
          Returns true if this Observation_ID is a pre-orbit ID, false if not.
 Observation_ID mission_phase_from_orbit_number(int orbit_number)
          Sets Mission_Phase component given the orbit number.
 Observation_ID mission_phase_from_time(int seconds)
          Sets Mission_Phase component given the number of seconds since the Observation_ID EPOCH.
 int mission_phase()
          Gets the Mission_Phase component of this Observation_ID.
 Observation_ID mission_phase(int the_mission_phase)
          Sets the Mission_Phase component of this Observation_ID.
 Observation_ID mission_phase(String mission_phase_text)
          Sets the Mission_Phase component of this Observation_ID from a string.
 Observation_ID mission_phase(String mission_phase_text, boolean use_defaults)
          Sets the Mission_Phase component of this Observation_ID from a string.
 int orbit_number()
          Gets the in-orbit Orbit_Number component of this Observation_ID.
 Observation_ID orbit_number(int the_orbit_number)
          Sets the in-orbit Orbit_Number component of this Observation_ID.
 Observation_ID orbit_number(String orbit_number_text)
          Sets the in-orbit Orbit_Number component of this Observation_ID based on a text string.
 Observation_ID orbit_number(String orbit_number_text, boolean use_defaults)
          Sets the in-orbit Orbit_Number component of this Observation_ID based on a text string.
 String parse(String the_text)
          Sets the value of this Observation_ID using a text representation.
 String parse(String id_text, boolean use_defaults)
          Sets the value of this Observation_ID using a text representation.
 int target()
          Gets the in-orbit Target component of this Observation_ID.
 Observation_ID target(int the_target)
          Sets the in-orbit Target component of this Observation_ID .
 Observation_ID target(String target_text)
          Sets the in-orbit Target component of this Observation_ID based on an text string.
 Observation_ID target(String target_text, boolean use_defaults)
          Sets the in-orbit Target component of this Observation_ID based on an text string.
 String text()
          Gets the text representation of this Observation_ID.
 Observation_ID text(String the_text)
          Sets the value of this Observation_ID using a text representation.
 Observation_ID text(String the_text, boolean use_defaults)
          Sets the value of this Observation_ID using a text representation.
 Observation_ID time_now()
          Sets the pre-orbit Time component of this Observation_ID to the current time, as determined from the system clock.
static String time_text_format()
          Gets the format used for formatting and interpretting time text.
static void time_text_format(String the_time_text_format)
          Sets the format used for formatting and interpretting time text.
 String time_text(int time_in_seconds)
          Produces a formatted text String from an integer number of seconds since the HiRISE EPOCH.
 String time_text(int time_in_seconds, int epoch)
          Produces a formatted text String from an integer number of seconds since a given epoch.
 int time()
          Gets the pre-orbit Time component of this Observation_ID.
 Observation_ID time(int the_time)
          Sets the pre-orbit Time component of this Observation_ID.
 Observation_ID time(String time_text)
          Sets the pre-orbit Time component of this Observation_ID from a string.
 Observation_ID time(String time_text, boolean use_defaults)
          Sets the pre-orbit Time component of this Observation_ID from a string.
 Observation_ID time(String time_text, String time_text_format)
          Sets the pre-orbit Time component of this Observation_ID from a string based on the specified time_text_format.
 Observation_ID time(String time_text, String time_text_format, boolean use_defaults)
          Sets the pre-orbit Time component of this Observation_ID from a string based on the specified time_text_format.
 String toString()
          Produces the text representation of this Observation_ID.
 int value()
          Gets the 32-bit numeric value of this Observation_ID.
 Observation_ID value(int value)
          Sets the 32-bit numeric value of this Observation_ID.
 Observation_ID value(String id_text)
          Sets this Observation_ID's numeric value using a string representing a 32-bit integer.
 Observation_ID value(String id_text, boolean use_defaults)
          Sets this Observation_ID's numeric value using a string representing a 32-bit integer.
static String zero_pad_binary(long number, int digits)
          Returns a zero-padded text string of a number in base-2 (binary) notation.
static String zero_pad_hex(long number, int digits)
          Returns a zero-padded text string of a number in base-16 (hexadecimal) notation.
static String zero_pad_number(long number, int digits)
          Returns a zero-padded text string of a number in base-10 (decimal) notation.
static String zero_pad_number(long number, int digits, int radix)
          Returns a zero-padded text string of a number in a given radix.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, 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

MISSION_PHASE_START

public static final int MISSION_PHASE_START
The index of the first Mission_Phase bit. Bits are indexed such that bit 0 determines whether an integer is even or odd.

See Also:
Constant Field Values

MISSION_PHASE_BIT_COUNT

public static final int MISSION_PHASE_BIT_COUNT
The number of bits used for the Mission_Phase component.

See Also:
Constant Field Values

MISSION_PHASE_MAX

public static final int MISSION_PHASE_MAX
The maximum value of the Mission_Phase component.

See Also:
Constant Field Values

MISSION_PHASE_MASK

public static final int MISSION_PHASE_MASK
The Mission_Phase bitmask. Each bit involved in the Mission_Phase component is ON; all others are OFF.

See Also:
Constant Field Values

TIME_START

public static final int TIME_START
The index of the first Time bit in a pre-orbit ID. Bits are indexed such that bit 0 determines whether an integer is even or odd.

See Also:
Constant Field Values

TIME_BIT_COUNT

public static final int TIME_BIT_COUNT
The number of bits used for the Time pre-orbit component.

See Also:
Constant Field Values

TIME_MAX

public static final int TIME_MAX
The maximum value of the Time pre-orbit component.

See Also:
Constant Field Values

TIME_MASK

public static final int TIME_MASK
The Time pre-orbit component bitmask. Each bit involed in the Time component is ON; all others are OFF.

See Also:
Constant Field Values

ORBIT_NUMBER_START

public static final int ORBIT_NUMBER_START
The index of the first Orbit_Number bit in an in-orbit ID. Bits are indexed such that bit 0 determines whether an integer is even or odd.

See Also:
Constant Field Values

ORBIT_NUMBER_BIT_COUNT

public static final int ORBIT_NUMBER_BIT_COUNT
The number of bits used for the Orbit_Number in-orbit component.

See Also:
Constant Field Values

ORBIT_NUMBER_MIN

public static final int ORBIT_NUMBER_MIN
The minimum value of the Orbit_Number in-orbit component.

See Also:
Constant Field Values

ORBIT_NUMBER_MAX

public static final int ORBIT_NUMBER_MAX
The maximum value of the Orbit_Number in-orbit component.

See Also:
Constant Field Values

ORBIT_NUMBER_MASK

public static final int ORBIT_NUMBER_MASK
The Orbit_Number in-orbit component bitmask. Each bit involved in the Orbit_Number is ON; all others are OFF.

See Also:
Constant Field Values

TARGET_START

public static final int TARGET_START
The index of the first Target bit in an in-orbit ID. Bits are indexed such that bit 0 determines whether an integer is even or odd.

See Also:
Constant Field Values

TARGET_BIT_COUNT

public static final int TARGET_BIT_COUNT
The number of bits used for the Target in-orbit component.

See Also:
Constant Field Values

TARGET_MAX

public static final int TARGET_MAX
The maximum value of the Target in-orbit component.

See Also:
Constant Field Values

TARGET_MASK

public static final int TARGET_MASK
The Target in-orbit component bitmask. Each bit involved in the Target is ON; all others are OFF.

See Also:
Constant Field Values

DEFAULT_TIME_TEXT_FORMAT

public static final String DEFAULT_TIME_TEXT_FORMAT
The default text format for the Time component of an Observation_ID. This format produces dates of the following form, using March 17, 2005, at 11:15 and 45 seconds in the evening as an example: 20050317T111545.

See Also:
Constant Field Values

PDS_TIME_TEXT_FORMAT

public static final String PDS_TIME_TEXT_FORMAT
The PDS format for the text representation of time. This format produces dates of the following form, using March 17, 2005, at 11:15 and 45 seconds in the evening as an example: 2005-03-17T11:15:45.

See Also:
Constant Field Values

RSDS_TIME_TEXT_FORMAT

public static final String RSDS_TIME_TEXT_FORMAT
The RSDS format for the text representation of time. This format produces dates of the following form, using March 17, 2005, at 11:15 and 45 seconds in the evening as an example: 2005.102.T111545.

See Also:
Constant Field Values

JPL_TIME_TEXT_FORMAT

public static final String JPL_TIME_TEXT_FORMAT
The JPL format for the text representation of time. This format produces dates of the following form, using March 17, 2005, at 11:15 and 45 seconds in the evening as an example: 2005-03-17T11:15:45.

See Also:
Constant Field Values

INTEGRATION_AND_TESTING

public static final int INTEGRATION_AND_TESTING
The integreation and testing mission phase. This phase is conducted at the HiRISE instrument manufacturer's facility.

See Also:
Constant Field Values

CALIBRATION

public static final int CALIBRATION
The calibration mission phase. This phase is conducted at the Mars Reconnaissance Orbiter spacecraft manufacturer's facility.

See Also:
Constant Field Values

ATLO

public static final int ATLO
The assembly, test, and launch operations mission phase. This phase is conducted at the spacecraft manufacturer's facility.

See Also:
Constant Field Values

KENNEDY_SPACE_CENTER

public static final int KENNEDY_SPACE_CENTER
The Kennedy Space Center mission phase. This phase is conducted at the spacecraft launch facility.

See Also:
Constant Field Values

LAUNCH

public static final int LAUNCH
The launch mission phase. This phase is conducted at the spacecraft launch facility.

See Also:
Constant Field Values

CRUISE

public static final int CRUISE
The cruise mission phase. This phase begins immediately after launch and continues until Mars approach. Numerous cruise operations are planned, including the "launch-plus-18-days" (L+18) spacecraft instrument checkout activity and the Lunar/Omega Centauri calibration activity.

See Also:
Constant Field Values

APPROACH

public static final int APPROACH
The approach mission phase. This phase ends the cruise to Mars.

See Also:
Constant Field Values

AEROBRAKING

public static final int AEROBRAKING
The aerobraking mission phase. This phase marks the first moment in which the spacecraft is in orbit around Mars.

See Also:
Constant Field Values

TRANSITION

public static final int TRANSITION
The transition mission phase. During this phase, the spacecraft's orbit is adjusted to its primary science orbit.

See Also:
Constant Field Values

PRIMARY_SCIENCE_PHASE

public static final int PRIMARY_SCIENCE_PHASE
The primary science mission phase. During this phase, the HiRISE instrument is expected to acquire roughly 10,000 images of the surface of Mars.

See Also:
Constant Field Values

RELAY

public static final int RELAY
The telecommunications relay mission phase. The Mars Reconnaissance Orbiter is part reconnaissance satellite, part communications satellite. After its primary science mission is completed, it will be used to relay data from other Mars spacecraft and surface probes back to Earth.

Note: This mission phase name has been abandoned by the MRO project. It has been renamed Extended Science Phase. We maintain this phase, Relay, for backwards compatibility with applications that expect it to exist.

See Also:
Constant Field Values

EXTENDED_SCIENCE_PHASE

public static final int EXTENDED_SCIENCE_PHASE
The extended science mission phase. This phase takes place immediately following the Primary Science Phase. It is an continuation of PSP and is part of the nominal MRO mission; it is not to be confused with an extended mission phase.

The Extended Science Phase was forerly called Relay, but the latter was abandoned in favor of a more accurate term.

See Also:
Constant Field Values

RESERVED_1

public static final int RESERVED_1
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_2

public static final int RESERVED_2
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_3

public static final int RESERVED_3
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_4

public static final int RESERVED_4
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_5

public static final int RESERVED_5
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_6

public static final int RESERVED_6
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_7

public static final int RESERVED_7
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_8

public static final int RESERVED_8
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_9

public static final int RESERVED_9
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_10

public static final int RESERVED_10
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_11

public static final int RESERVED_11
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_12

public static final int RESERVED_12
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_13

public static final int RESERVED_13
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_14

public static final int RESERVED_14
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_15

public static final int RESERVED_15
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_16

public static final int RESERVED_16
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_17

public static final int RESERVED_17
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_18

public static final int RESERVED_18
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

RESERVED_19

public static final int RESERVED_19
A reserved mission phase. The mission planning team expects to have several extended missions added after the end of the primary science phase. This phase is a placeholder for the expected extended mission phase.

See Also:
Constant Field Values

SVT

public static final int SVT
The sequence verification tests mission phase. Although this phase is conducted during assembly, test, and launch operations (ATLO), it is conducted in orbit-like conditions, requiring an in-orbit mission phase.

See Also:
Constant Field Values

TOTAL_MISSION_PHASES

public static final int TOTAL_MISSION_PHASES
The total number of mission phases.

See Also:
Constant Field Values

LAST_PREORBIT_PHASE

public static final int LAST_PREORBIT_PHASE
The last pre-orbit mission phase. Mission phases beyond this value are considered to be in-orbit phases.

See Also:
Constant Field Values

DEFAULT_PREORBIT_PHASE

public static final int DEFAULT_PREORBIT_PHASE
The default mission phase for pre-orbit observations.

See Also:
Constant Field Values

DEFAULT_INORBIT_PHASE

public static final int DEFAULT_INORBIT_PHASE
The default mission phase for in-orbit observations.

See Also:
Constant Field Values

DEFAULT_MISSION_PHASE

public static final int DEFAULT_MISSION_PHASE
The default mission phase.

See Also:
Constant Field Values

MISSION_PHASE_ABBREVIATION

public static final String[] MISSION_PHASE_ABBREVIATION
The three-letter text representation of each mission phase, indexed by the 32 mission phase constants. The values of this array are used in the text representation of the Observation_ID.


MISSION_PHASE_NAME

public static final String[] MISSION_PHASE_NAME
The full descriptive name of each mission phase, indexed by the 32 mission phase constants. The values of this array are not used by the text representation of the Observation_ID, but they are used in exception messages, and they may be suitable for other uses as well. A JComboBox that presents the individual mission phases might use this array, for example.


MISSION_PHASE_MAX_TIME

public static final int[] MISSION_PHASE_MAX_TIME
The times/dates associated with the mission phases. These times are given as the number of seconds since the HiRISE Observation_ID.EPOCH and represent the maximum date for that mission phase. They are indexed by Mission_Phase. Note that January 19, 2038, 03:14:07 UTC is the end-of-time for most 32-bit Unix systems; this date corresponds to 1,074,568,447 seconds after the HiRISE Observation_ID::EPOCH.


MISSION_PHASE_MAX_ORBIT

public static final int[] MISSION_PHASE_MAX_ORBIT
The orbit numbers associated with the mission phases. These orbits are indexed by Mission_Phase.


INVALID_OBSERVATION_ID

public static final int INVALID_OBSERVATION_ID
The invalid Observation_ID value.

See Also:
Constant Field Values

DEFAULT_OBSERVATION_ID

public static final int DEFAULT_OBSERVATION_ID
The default Observation_ID value.

See Also:
Constant Field Values

DEFAULT_TIME

public static final int DEFAULT_TIME
The default value for the Time component of a pre-orbit Observation_ID.

See Also:
Constant Field Values

DEFAULT_ORBIT_NUMBER

public static final int DEFAULT_ORBIT_NUMBER
The default value for the Orbit_Number component of an in-orbit Observation_ID.

See Also:
Constant Field Values

DEFAULT_TARGET

public static final int DEFAULT_TARGET
The default value for the Target component of an in-orbit Observation_ID.

See Also:
Constant Field Values

TEXT_DELIMITER

public static final char TEXT_DELIMITER
A text delimiter used in parsing Observation_ID text.

See Also:
Constant Field Values

EXTENSION_DELIMITER

public static final char EXTENSION_DELIMITER
An extension delimiter used in parsing Observation_ID text.

See Also:
Constant Field Values

EPOCH

public static final int EPOCH
Reference date for Observation_ID pre-orbit times. This number is the number of seconds since the standard Unix epoch of Jan 1, 1970, 00:00:00 UTC. The HiRISE epoch is Jan 1, 2004, 00:00:00 UTC.

See Also:
Constant Field Values

DELIMITER_PATTERN

protected static final String DELIMITER_PATTERN
See Also:
Constant Field Values

REQUIRED_DELIMITER_PATTERN

protected static final String REQUIRED_DELIMITER_PATTERN
See Also:
Constant Field Values

OPTIONAL_DELIMITER_PATTERN

protected static final String OPTIONAL_DELIMITER_PATTERN
See Also:
Constant Field Values

PREFIX_PATTERN

protected static final String PREFIX_PATTERN
See Also:
Constant Field Values

SUFFIX_PATTERN

protected static final String SUFFIX_PATTERN
See Also:
Constant Field Values

MISSION_PHASE_PATTERN

protected static final String MISSION_PHASE_PATTERN
See Also:
Constant Field Values

TIME_PATTERN

protected static final String TIME_PATTERN
See Also:
Constant Field Values

ORBIT_NUMBER_PATTERN

protected static final String ORBIT_NUMBER_PATTERN
See Also:
Constant Field Values

TARGET_PATTERN

protected static final String TARGET_PATTERN
See Also:
Constant Field Values

PREORBIT_PREFIX_GROUP

protected static final int PREORBIT_PREFIX_GROUP
See Also:
Constant Field Values

PREORBIT_MISSION_PHASE_GROUP

protected static final int PREORBIT_MISSION_PHASE_GROUP
See Also:
Constant Field Values

PREORBIT_TIME_GROUP

protected static final int PREORBIT_TIME_GROUP
See Also:
Constant Field Values

PREORBIT_SUFFIX_GROUP

protected static final int PREORBIT_SUFFIX_GROUP
See Also:
Constant Field Values

INORBIT_PREFIX_GROUP

protected static final int INORBIT_PREFIX_GROUP
See Also:
Constant Field Values

INORBIT_MISSION_PHASE_GROUP

protected static final int INORBIT_MISSION_PHASE_GROUP
See Also:
Constant Field Values

INORBIT_ORBIT_NUMBER_GROUP

protected static final int INORBIT_ORBIT_NUMBER_GROUP
See Also:
Constant Field Values

INORBIT_TARGET_GROUP

protected static final int INORBIT_TARGET_GROUP
See Also:
Constant Field Values

INORBIT_SUFFIX_GROUP

protected static final int INORBIT_SUFFIX_GROUP
See Also:
Constant Field Values

TEST_ID_PATTERN

protected static final String TEST_ID_PATTERN
See Also:
Constant Field Values

SPACECRAFT_ID_PATTERN

protected static final String SPACECRAFT_ID_PATTERN
See Also:
Constant Field Values

INSTRUMENT_ID_PATTERN

protected static final String INSTRUMENT_ID_PATTERN
See Also:
Constant Field Values

OBSERVATION_ID_PATTERN

protected static final String OBSERVATION_ID_PATTERN
See Also:
Constant Field Values

CPMM_AND_CHANNEL_PATTERN

protected static final String CPMM_AND_CHANNEL_PATTERN
See Also:
Constant Field Values

GAP_INDICATOR_PATTERN

protected static final String GAP_INDICATOR_PATTERN
See Also:
Constant Field Values

VERSION_PATTERN

protected static final String VERSION_PATTERN
See Also:
Constant Field Values

EXTENSION_PATTERN

protected static final String EXTENSION_PATTERN
See Also:
Constant Field Values

RSDS_OPS_SPACECRAFT_ID_GROUP

protected static final int RSDS_OPS_SPACECRAFT_ID_GROUP
See Also:
Constant Field Values

RSDS_OPS_INSTRUMENT_ID_GROUP

protected static final int RSDS_OPS_INSTRUMENT_ID_GROUP
See Also:
Constant Field Values

RSDS_OPS_OBSERVATION_ID_GROUP

protected static final int RSDS_OPS_OBSERVATION_ID_GROUP
See Also:
Constant Field Values

RSDS_OPS_CPMM_AND_CHANNEL_GROUP

protected static final int RSDS_OPS_CPMM_AND_CHANNEL_GROUP
See Also:
Constant Field Values

RSDS_OPS_GAP_GROUP

protected static final int RSDS_OPS_GAP_GROUP
See Also:
Constant Field Values

RSDS_OPS_VERSION_GROUP

protected static final int RSDS_OPS_VERSION_GROUP
See Also:
Constant Field Values

RSDS_OPS_EXTENSION_GROUP

protected static final int RSDS_OPS_EXTENSION_GROUP
See Also:
Constant Field Values

RSDS_TEST_ID_GROUP

protected static final int RSDS_TEST_ID_GROUP
See Also:
Constant Field Values

RSDS_TEST_SPACECRAFT_ID_GROUP

protected static final int RSDS_TEST_SPACECRAFT_ID_GROUP
See Also:
Constant Field Values

RSDS_TEST_INSTRUMENT_ID_GROUP

protected static final int RSDS_TEST_INSTRUMENT_ID_GROUP
See Also:
Constant Field Values

RSDS_TEST_OBSERVATION_ID_GROUP

protected static final int RSDS_TEST_OBSERVATION_ID_GROUP
See Also:
Constant Field Values

RSDS_TEST_CPMM_AND_CHANNEL_GROUP

protected static final int RSDS_TEST_CPMM_AND_CHANNEL_GROUP
See Also:
Constant Field Values

RSDS_TEST_GAP_GROUP

protected static final int RSDS_TEST_GAP_GROUP
See Also:
Constant Field Values

RSDS_TEST_VERSION_GROUP

protected static final int RSDS_TEST_VERSION_GROUP
See Also:
Constant Field Values

RSDS_TEST_EXTENSION_GROUP

protected static final int RSDS_TEST_EXTENSION_GROUP
See Also:
Constant Field Values
Constructor Detail

Observation_ID

public Observation_ID()
Creates a default Observation_ID, whose value is DEFAULT_OBSERVATION_ID.


Observation_ID

public Observation_ID(int value)
Creates an Observation_ID with the specified value.

Parameters:
value - the numeric value of the new Observation_ID.

Observation_ID

public Observation_ID(int the_mission_phase,
                      int the_time)
Creates a pre-orbit Observation_ID with the specified Mission_Phase and Time components. If the_mission_phase is not a pre-orbit mission phase, DEFAULT_PREORBIT_PHASE will be used instead. If the_time is less than 0, the current time, as determined from the system clock, will be used. If the_time is greater than TIME_MAX, DEFAULT_TIME will be used instead.

Parameters:
the_mission_phase - the pre-orbit mission phase for the new Observation_ID.
the_time - the Time component for the new Observation_ID.

Observation_ID

public Observation_ID(int the_mission_phase,
                      int the_orbit_number,
                      int the_target)
Creates an in-orbit Observation_ID with the specified Mission_Phase, Orbit_Number, and Target components. If the_mission_phase is not an in-orbit mission phase, DEFAULT_INORBIT_PHASE will be used instead. If the_orbit_number is less than 0 or greater than ORBIT_NUMBER_MAX, DEFAULT_ORBIT_NUMBER will be used instead. If the_target is less than 0 or greater than TARGET_MAX, DEFAULT_TARGET will be used instead.

Parameters:
the_mission_phase - The in-orbit mission phase for the new Observation_ID.
the_orbit_number - The Orbit_Number component for the new Observation_ID.
the_target - The Target component for the new Observation_ID.

Observation_ID

public Observation_ID(String the_id_text)
Creates an Observation_ID based on a text string. If the text string cannot be interpretted as a valid Observation_ID, INVALID_OBSERVATION_ID will be used instead.

Method Detail

value

public int value()
Gets the 32-bit numeric value of this Observation_ID. Because the Java language does not support an unsigned 32-bit integer primitive data type, some care may be needed before displaying this numeric value to an operator.

Returns:
The 32-bit numeric representation of this Observation_ID.

value

public Observation_ID value(int value)
Sets the 32-bit numeric value of this Observation_ID.

Parameters:
value - The new 32-bit value of this Observation_ID.
Returns:
A reference back to this Observation_ID.

value

public Observation_ID value(String id_text,
                            boolean use_defaults)
                     throws Invalid_Argument_Exception
Sets this Observation_ID's numeric value using a string representing a 32-bit integer. If id_text cannot be parsed for a valid observation ID, an Invalid_Argument_Exception is thrown. If use_defaults is true, the DEFAULT_OBSERVATION_ID will be used instead.

Parameters:
id_text - The text from which the Observation_ID's new value will be parsed. It must be an 32-bit integer. It may be zero-padded.
use_defaults - If true, DEFAULT_OBSERVATION_ID will be used if the value cannot be parsed; otherwise, an Invalid_Argument_Exception will be thrown.
Returns:
A reference back to this Observation_ID.
Throws:
Invalid_Argument_Exception - If no valid value can be parsed from the argument.

value

public Observation_ID value(String id_text)
Sets this Observation_ID's numeric value using a string representing a 32-bit integer. This method calls value(String,boolean) with use_defaults set to true.

Parameters:
id_text - The text from which the Observation_ID's new value will be parsed. It must be an 32-bit integer. It may be zero-padded.
Returns:
A reference back to this Observation_ID.
See Also:
value(String, boolean)

hex_value

public Observation_ID hex_value(String id_text,
                                boolean use_defaults)
                         throws Invalid_Argument_Exception
Sets this Observation_ID's numeric value using a string representing a hexadecimal 32-bit integer. If id_text cannot be parsed for a valid observation ID, an Invalid_Argument_Exception is thrown. If use_defaults is true, the DEFAULT_OBSERVATION_ID will be used instead.

Parameters:
id_text - The text from which the Observation_ID's new value will be parsed. It must be an hexadecimal 32-bit integer. It may be zero-padded.
use_defaults - If true, DEFAULT_OBSERVATION_ID will be used if the hex_value cannot be parsed; otherwise, an Invalid_Argument_Exception will be thrown.
Returns:
A reference back to this Observation_ID.
Throws:
Invalid_Argument_Exception - If no valid value can be parsed from the argument.

hex_value

public Observation_ID hex_value(String id_text)
Sets this Observation_ID's numeric value using a string representing a hexidecimal 32-bit integer. This method calls hex_value(String,boolean) with use_defaults set to true.

Parameters:
id_text - The text from which the Observation_ID's new value will be parsed. It must be an 32-bit integer. It may be zero-padded.
Returns:
A reference back to this Observation_ID.
See Also:
hex_value(String, boolean)

mission_phase

public int mission_phase()
Gets the Mission_Phase component of this Observation_ID. The value of this component will be one of the mission phase constants of the Observation_ID class.

Returns:
The Mission_Phase component of this Observation_ID.

mission_phase

public Observation_ID mission_phase(int the_mission_phase)
                             throws Out_of_Range_Exception
Sets the Mission_Phase component of this Observation_ID. The value of this component must be one of the mission phase constants of the Observation_ID class, or an Out_of_Range_Exception will be thrown.

Note that if a pre-orbit ID has its mission phase set to an in-orbit phase, the correct interpretation of the resulting ID's Orbit_Number and Target components is uncertain. Likewise, if an in-orbit ID is converted to a pre-orbit ID, the Time component is suspect.

Parameters:
the_mission_phase - The new Mission_Phase component of this Observation_ID.
Returns:
A reference back to this Observation_ID.
Throws:
Out_of_Range_Exception - If the_mission_phase is out of range.

mission_phase

public Observation_ID mission_phase(String mission_phase_text,
                                    boolean use_defaults)
                             throws Out_of_Range_Exception,
                                    Invalid_Argument_Exception
Sets the Mission_Phase component of this Observation_ID from a string. This method compares the mission_phase_text to the MISSION_PHASE_NAME and MISSION_PHASE_ABBREVIATION arrays. The comparison is done ignoring case and, for the latter comparison, ignoring delimiters as defined by DELIMITER_PATTERN. If mission_phase_text cannot be parsed for a valid mission phase, an Invalid_Argument_Exception is thrown. Or if the mission phase is out of range, an Out_of_Range_Exception is thrown. If use_defaults is true, the DEFAULT_MISSION_PHASE will be used instead.

Parameters:
mission_phase_text - The text from which the mission phase will be parsed.
use_defaults - If true, DEFAULT_MISSION_PHASE will be used if the mission phase cannot be parsed or if the value is out of range; otherwise, an Invalid_Argument_Exception or Out_of_Range_Exception will be thrown.
Returns:
A reference back to this Observation_ID.
Throws:
Out_of_Range_Exception - If parsed the_mission_phase is out of range.
Invalid_Argument_Exception - If no valid mission phase could be parsed from mission_phase_text.

mission_phase

public Observation_ID mission_phase(String mission_phase_text)
Sets the Mission_Phase component of this Observation_ID from a string. This method calls mission_phase(String,boolean) with use_defaults set to true.

Parameters:
mission_phase_text - The text from which the mission phase will be parsed.
Returns:
A reference back to this Observation_ID.
See Also:
mission_phase(String, boolean)

mission_phase_from_time

public Observation_ID mission_phase_from_time(int seconds)
                                       throws Out_of_Range_Exception
Sets Mission_Phase component given the number of seconds since the Observation_ID EPOCH. If seconds is negative, then the current system time will be used. If the current system time happens to be prior to the Observation_ID EPOCH, then the Observation_ID EPOCH will be used instead. This method compares seconds to the different elements of the MISSION_PHASE_MAX_TIME array, using the first value that to which seconds is less than or equal to derive a mission phase. It is important to note that seconds is relative to the Observation_ID epoch (Jan 1, 2004, 00:00:00 UTC), not the Unix epoch (Jan 1, 1970, 00:00:00 UTC). Because of this distinction, it is possible to supply a seconds value that represents a time greater than the Unix 32-bit maximum date of January 19, 2038, 03:14:07 UTC. In this case, this method will throw an Out_of_Range_Exception. It is equally important to note that seconds may be greater than Observation_ID.TIME_MAX, which applies only to calculations involving the time component of a pre-orbit Observation_ID. Thus, this method may set the mission phase component to an in-orbit value if not used carefully.

Parameters:
seconds - The number of seconds since the Observation_ID.EPOCH.
Throws:
Out_of_Range_Exception - If seconds represents a time greater than January 19, 2038, 03:14:07 UTC.

mission_phase_from_orbit_number

public Observation_ID mission_phase_from_orbit_number(int orbit_number)
                                               throws Out_of_Range_Exception
Sets Mission_Phase component given the orbit number. This method compares seconds to the different elements of the MISSION_PHASE_MAX_ORBIT array, using the first value that to which the orbit number is less than or equal to derive a mission phase. If the orbit_number is less than ORBIT_NUMBER_MIN or greater than ORBIT_NUMBER_MAX an Out_of_Range_Exception will be thrown.

Parameters:
orbit_number - The orbit_number to use to return the mission_phase.
Throws:
Out_of_Range_Exception - If orbit_number is less than ORBIT_NUMBER_MIN or greater than ORBIT_NUMBER_MAX.

time

public int time()
         throws Out_of_Range_Exception
Gets the pre-orbit Time component of this Observation_ID. If the ID is not a pre-orbit ID, an Out_of_Range_Exception will be thrown.

Returns:
The Time component of this Observation_ID.
Throws:
Out_of_Range_Exception - If the ID is not a pre-orbit ID.

time

public Observation_ID time(int the_time)
                    throws Out_of_Range_Exception
Sets the pre-orbit Time component of this Observation_ID. If the ID is not a pre-orbit ID, an Out_of_Range_Exception will be thrown. Futhermore, if the_time is less than 0 or greater than TIME_MAX, an Out_of_Range_Exception will be thrown.

Parameters:
the_time - The new value for the Time component of this Observation_ID.
Returns:
A reference back to this Observation_ID.
Throws:
Out_of_Range_Exception - If the ID is not a pre-orbit ID or if the_time is out of range.

time

public Observation_ID time(String time_text,
                           boolean use_defaults)
                    throws Out_of_Range_Exception,
                           Invalid_Argument_Exception
Sets the pre-orbit Time component of this Observation_ID from a string. This method uses the extract_time(java.lang.String, boolean) function to parse the time; the format is the current value of time_text_format. If time_text cannot be parsed for a valid time, an Invalid_Argument_Exception is thrown. Or if the parsed time is less than 0 or greater than TIME_MAX or if the ID is not a pre-orbit ID, an Out_of_Range_Exception is thrown. If use_defaults is true, the DEFAULT_TIME will be used instead.

Parameters:
time_text - The text from which the time will be parsed.
use_defaults - If true, DEFAULT_TIME will be used if the time cannot be parsed or if the parsed value is out of range; otherwise, an Invalid_Argument_Exception or Out_of_Range_Exception will be thrown.
Returns:
A reference back to this Observation_ID.
Throws:
Invalid_Argument_Exception - If no valid time component could be parsed from time_text given time_format or if this Observation_ID is not a pre-orbit ID.
Out_of_Range_Exception - If the parsed time component falls outside the range [EPOCH, EPOCH + TIME_MAX] or if the ID is not a pre-orbit ID.

time

public Observation_ID time(String time_text)
Sets the pre-orbit Time component of this Observation_ID from a string. This method calls time(String,boolean) with use_defaults set to true.

Parameters:
time_text - The text from which the time will be parsed.
Returns:
A reference back to this Observation_ID.
See Also:
time(String, boolean)

time

public Observation_ID time(String time_text,
                           String time_text_format,
                           boolean use_defaults)
                    throws Out_of_Range_Exception,
                           Invalid_Argument_Exception
Sets the pre-orbit Time component of this Observation_ID from a string based on the specified time_text_format. This method uses the extract_time(java.lang.String, boolean) function to parse the time; the format is the value of time_text_format. If time_text cannot be parsed for a valid time, an Out_of_Range_Exception is thrown. Or if the parsed time is less than 0 or greater than TIME_MAX or if the ID is not a pre-orbit ID, an Out_of_Range_Exception is thrown. If use_defaults is true, the DEFAULT_TIME will be used instead.

Parameters:
time_text - The text from which the time will be parsed.
use_defaults - If true, DEFAULT_TIME will be used if the time cannot be parsed or if the parsed value is out of range; otherwise, an Invalid_Argument_Exception or Out_of_Range_Exception will be thrown.
Returns:
A reference back to this Observation_ID.
Throws:
Invalid_Argument_Exception - If no valid time component could be parsed from time_text given time_format or if this Observation_ID is not a pre-orbit ID.
Out_of_Range_Exception - If the parsed time component falls outside the range [EPOCH, EPOCH + TIME_MAX] or if the ID is not a pre-orbit ID.

time

public Observation_ID time(String time_text,
                           String time_text_format)
Sets the pre-orbit Time component of this Observation_ID from a string based on the specified time_text_format. This method calls time(String, String, boolean) with use_defaults set to true.

Parameters:
time_text - The text from which the time will be parsed.
Returns:
A reference back to this Observation_ID.
See Also:
time(String,String,boolean)

time_now

public Observation_ID time_now()
                        throws Out_of_Range_Exception
Sets the pre-orbit Time component of this Observation_ID to the current time, as determined from the system clock. If the ID is not a pre-orbit ID, an Out_of_Range_Exception will be thrown. If the current system time is less than the EPOCH, 0 will be used instead, reflecting 0 seconds after the HiRISE epoch. If the Time component would be greater than TIME_MAX, then TIME_MAX will be used instead.

Returns:
A reference back to this Observation_ID.
Throws:
Out_of_Range_Exception - If the ID is not a pre-orbit ID.

orbit_number

public int orbit_number()
                 throws Out_of_Range_Exception
Gets the in-orbit Orbit_Number component of this Observation_ID. If the ID is not an in-orbit ID, an Out_of_Range_Exception is thrown.

Returns:
The Orbit_Number component of this Observation_ID.
Throws:
Out_of_Range_Exception - If the ID is not an in-orbit ID.

orbit_number

public Observation_ID orbit_number(int the_orbit_number)
                            throws Out_of_Range_Exception
Sets the in-orbit Orbit_Number component of this Observation_ID. If the ID is not an in-orbit ID, an Out_of_Range_Exception is thrown. If the_orbit_number is less than 0 or greater than ORBIT_NUMBER_MAX, an Out_of_Range_Exception is thrown.

Parameters:
the_orbit_number - The new orbit number for this Observation_ID
Returns:
A reference back to this Observation_ID.
Throws:
Out_of_Range_Exception - If the ID is not an in-orbit ID or if the_orbit_number is out of range.

orbit_number

public Observation_ID orbit_number(String orbit_number_text,
                                   boolean use_defaults)
                            throws Invalid_Argument_Exception,
                                   Out_of_Range_Exception
Sets the in-orbit Orbit_Number component of this Observation_ID based on a text string. If the orbit number cannot be parsed from the string, an Invalid_Argument_Exception is thrown. Or if orbit number is less than 0 or greater than ORBIT_NUMBER_MAX, an Out_of_Range_Exception is thrown. If use_defaults is true, the DEFAULT_ORBIT_NUMBER will be used instead.

Parameters:
orbit_number_text - The text from which to extract the new orbit number for this Observation_ID
use_defaults - If true, DEFAULT_ORBIT_NUMBER will be used if the orbit number cannot be parsed or if the parsed value is out of range; otherwise, an Invalid_Argument_Exception or Out_of_Range_Exception will be thrown.
Returns:
A reference back to this Observation_ID.
Throws:
Invalid_Argument_Exception - If the ID cannot be extracted from the orbit_number_text.
Out_of_Range_Exception - If the ID is not an in-orbit ID or if the_orbit_number is out of range.

orbit_number

public Observation_ID orbit_number(String orbit_number_text)
Sets the in-orbit Orbit_Number component of this Observation_ID based on a text string. This method calls orbit_number(String,boolean) with use_defaults set to true.

Parameters:
orbit_number_text - The text from which to extract the new orbit number for this Observation_ID
Returns:
A reference back to this Observation_ID.
See Also:
orbit_number(String, boolean)

target

public int target()
           throws Out_of_Range_Exception
Gets the in-orbit Target component of this Observation_ID. If the ID is not an in-orbit ID, an Out_of_Range_Exception is thrown.

Returns:
The Target component of this Observation_ID.
Throws:
Out_of_Range_Exception - If the ID is not an in-orbit ID.

target

public Observation_ID target(int the_target)
                      throws Out_of_Range_Exception
Sets the in-orbit Target component of this Observation_ID . If the ID is not an in-orbit ID, an Out_of_Range_Exception is thrown. If the_target is less than 0 or greater than TARGET_MAX, and Out_of_Range_Exception is thrown.

Note that the_target is the numeric representation (N) of the Target, not the text representation (T).

Parameters:
the_target - The numeric value of the target for this Observation_ID
Returns:
A reference back to this Observation_ID.
Throws:
Out_of_Range_Exception - If the ID is not an in-orbit ID or if the_target is out of range.

target

public Observation_ID target(String target_text,
                             boolean use_defaults)
                      throws Invalid_Argument_Exception,
                             Out_of_Range_Exception
Sets the in-orbit Target component of this Observation_ID based on an text string. If the target cannot be parsed from the string, an Invalid_Argument_Exception is thrown. If target is less than 0 or greater than TARGET_MAX, an Out_of_Range_Exception is thrown. If use_defaults is true, the DEFAULT_TARGET will be used instead.

Note that the_target is the numeric representation (N) of the Target, not the text representation (T).

Parameters:
target_text - The numeric value of the target for this Observation_ID
use_defaults - If true, DEFAULT_TARGET will be used if the target cannot be parsed or if the parsed value is out of range; otherwise, an Invalid_Argument_Exception or Out_of_Range_Exception will be thrown.
Returns:
A reference back to this Observation_ID.
Throws:
Invalid_Argument_Exception - If the target cannot be extracted from the target_text.
Out_of_Range_Exception - If the ID is not an in-orbit ID or if the_target is out of range.

target

public Observation_ID target(String target_text)
Sets the in-orbit Target component of this Observation_ID based on an text string. This method calls time(String,boolean) with use_defaults set to true.

Parameters:
target_text - The numeric value of the target for this Observation_ID
Returns:
A reference back to this Observation_ID.
See Also:
text(String, boolean)

text

public String text()
Gets the text representation of this Observation_ID. The text representation is discussed in detail in the Observation_ID overview.

Returns:
The text representation of this Observation_ID.

text

public Observation_ID text(String the_text,
                           boolean use_defaults)
                    throws Invalid_Argument_Exception,
                           Out_of_Range_Exception
Sets the value of this Observation_ID using a text representation. If the_text cannot be parsed for a valid observation ID, an Invalid_Argument_Exception is thrown. If use_defaults is true, appropriate default values will be used as needed instead.

Parameters:
the_text - The text from which to parse an observation ID.
use_defaults - If true, default values for the various components of an Observation_ID will be used when they cannot be determined from the_text. If false, an Invalid_Argument_Exception will be thrown instead.
Returns:
A reference to this Observation_ID.
Throws:
Invalid_Argument_Exception - If an observation ID cannot be parsed from the_text and use_defaults is false.
Out_of_Range_Exception - If a one of the parsed values is out of range and use_defaults is false.
See Also:
parse(String,boolean)

text

public Observation_ID text(String the_text)
Sets the value of this Observation_ID using a text representation. If the_text cannot be parsed for a valid observation ID, appropriate default values will be used as needed instead. This method calls parse(String,boolean) with use_defaults set to true.

Parameters:
the_text - The text from which to parse an observation ID.
Returns:
A reference to this Observation_ID.
See Also:
parse(String,boolean)

is_preorbit

public boolean is_preorbit()
Returns true if this Observation_ID is a pre-orbit ID, false if not.

Returns:
true if this Observation_ID is a pre-orbit ID, false if not.

time_text

public String time_text(int time_in_seconds,
                        int epoch)
Produces a formatted text String from an integer number of seconds since a given epoch. The format of the text may be changed by an invocation of the time_text_format(String) method.

Parameters:
time_in_seconds - The number of seconds since the epoch.
epoch - A reference point in time; the number of seconds since the Unix epoch of Jan 1, 1970, 00:00:00 UTC.
Returns:
A formatted text representation of the time.
See Also:
time_text_format(String)

time_text

public String time_text(int time_in_seconds)
Produces a formatted text String from an integer number of seconds since the HiRISE EPOCH. The format of the text may be changed by an invocation of the time_text_format(String) method.

Parameters:
time_in_seconds - The number of seconds since the HiRISE EPOCH.
Returns:
A formatted text representation of the time.
See Also:
time_text_format(String)

toString

public String toString()
Produces the text representation of this Observation_ID.

Overrides:
toString in class Object
Returns:
The text representation of this Observation_ID.
See Also:
text()

parse

public String parse(String id_text,
                    boolean use_defaults)
             throws Invalid_Argument_Exception,
                    Out_of_Range_Exception
Sets the value of this Observation_ID using a text representation. If the_text cannot be parsed for a valid observation ID, an Invalid_Argument_Exception is thrown. If use_defaults is true, appropriate default values will be used as needed instead.

This method returns the text that was not used in the interpretation of an observation ID. Subclasses of Observation_ID can use this returned text to parse additional information.

Parameters:
id_text - The text from which to parse an observation ID.
use_defaults - If true, default values for the various components of an Observation_ID will be used when they cannot be determined from the_text. If false, an Invalid_Argument_Exception will be thrown instead.
Returns:
Text not used in the interpretation of an observation ID.
Throws:
Invalid_Argument_Exception - If an observation ID cannot be parsed from the_text and use_defaults is false.
Out_of_Range_Exception - If a one of the parsed values is out of range and use_defaults is false.

parse

public String parse(String the_text)
Sets the value of this Observation_ID using a text representation. If the_text cannot be parsed for a valid observation ID, appropriate default values will be used as needed instead. This method calls parse(String,boolean) with use_defaults set to true.

This method returns the text that was not used in the interpretation of an observation ID. Subclasses of Observation_ID can use this returned text to parse additional information.

Parameters:
the_text - The text from which to parse an observation ID.
Returns:
Text not used in the interpretation of an observation ID.
See Also:
text(String, boolean)

extract_mission_phase

public static int extract_mission_phase(String the_text,
                                        boolean use_defaults)
                                 throws Invalid_Argument_Exception
Parses a Mission_Phase component from a text String.

Parameters:
the_text - The text to be parsed.
use_defaults - If true, a DEFAULT_MISSION_PHASE will be used if a mission phase cannot be parsed; otherwise, an Invalid_Argument_Exception will be thrown.
Returns:
A Mission_Phase.
Throws:
Invalid_Argument_Exception - If a mission phase cannot be parsed from the_text and use_defaults is false.

extract_mission_phase

public static int extract_mission_phase(String the_text)
Parses a Mission_Phase component from a text String. If a mission phase cannot be parsed from the_text, a DEFAULT_MISSION_PHASE will be returned.

Parameters:
the_text - the text to be parsed.
Returns:
a Mission_Phase.

extract_time

public static int extract_time(String the_text,
                               boolean use_defaults)
                        throws Invalid_Argument_Exception
Parses a Time pre-orbit component from a text String.

Parameters:
the_text - The text to be parsed.
use_defaults - If true, a DEFAULT_TIME will be used if a time cannot be parsed; otherwise, an Invalid_Argument_Exception will be thrown.
Returns:
A Time, in seconds since the HiRISE EPOCH.
Throws:
Invalid_Argument_Exception - If a time cannot be parsed from the_text and use_defaults is false.

extract_time

public static int extract_time(String the_text)
Parses a Time pre-orbit component from a text String. If a time cannot be parsed from the_text, a DEFAULT_TIME will be returned.

Parameters:
the_text - The text to be parsed.
Returns:
A Time, in seconds since the HiRISE EPOCH.

extract_orbit_number

public static int extract_orbit_number(String the_text,
                                       boolean use_defaults)
                                throws Invalid_Argument_Exception
Parses an Orbit_Number in-orbit component from a text String.

Parameters:
the_text - The text to be parsed.
use_defaults - If true, a DEFAULT_ORBIT_NUMBER will be used if an orbit number cannot be parsed; otherwise, an Invalid_Argument_Exception will be thrown.
Returns:
An Orbit_Number.
Throws:
Invalid_Argument_Exception - If an orbit number cannot be parsed from the_text and use_defaults is false.

extract_orbit_number

public static int extract_orbit_number(String the_text)
Parses an Orbit_Number in-orbit component from a text String. If an orbit number cannot be parsed from the_text, a DEFAULT_ORBIT_NUMBER will be returned.

Parameters:
the_text - The text to be parsed.
Returns:
An Orbit_Number.

extract_target

public static int extract_target(String the_text,
                                 boolean use_defaults)
                          throws Invalid_Argument_Exception
Parses a Target in-orbit component from a text String. The target number is expected to be in text form (T), not in numeric form (N).

Parameters:
the_text - The text to be parsed.
use_defaults - If true, a DEFAULT_TARGET will be used if a target cannot be parsed; otherwise, an Invalid_Argument_Exception will be thrown.
Returns:
a Target.
Throws:
Invalid_Argument_Exception - If a target cannot be parsed from the_text and use_defaults is false.

extract_target

public static int extract_target(String the_text)
Parses a Target in-orbit component from a text String. If a target cannot be parsed from the_text, a DEFAULT_TARGET will be returned. The target number is expected to be in text form (T), not in numeric form (N).

Parameters:
the_text - The text to be parsed.
Returns:
A Target.

time_text_format

public static String time_text_format()
Gets the format used for formatting and interpretting time text. This format is used by the time_text(int,int) method, the parse(String,boolean) method, and the extract_time(String,boolean) method. It is also used in the creation of the Observation_ID's text representation, via the text() method and the toString() method.

Returns:
The time text format.

time_text_format

public static void time_text_format(String the_time_text_format)
                             throws Invalid_Argument_Exception
Sets the format used for formatting and interpretting time text. This format is used by the time_text(int,int) method, the parse(String,boolean) method, and the extract_time(String,boolean) method. It is also used in the creation of the Observation_ID's text representation, via the text() method and the toString() method.

This method should be used with care, since it alters the way in which putative observation ID text will be interpretted.

Parameters:
the_time_text_format - The new format to be used.
Throws:
Invalid_Argument_Exception - If the_time_text_format includes an underscore, which has special meaning in interpretting an observation ID.

zero_pad_number

public static String zero_pad_number(long number,
                                     int digits,
                                     int radix)
Returns a zero-padded text string of a number in a given radix. The formatted text does not include a prefix indication of the radix used.

Parameters:
number - The number to format.
digits - The minimum number of digits to return.
radix - The base used to format the number.
Returns:
The zero-padded text representation of the number.

zero_pad_number

public static String zero_pad_number(long number,
                                     int digits)
Returns a zero-padded text string of a number in base-10 (decimal) notation.

Parameters:
number - The number to format.
digits - The minimum number of digits to return.
Returns:
The zero-padded text representation of the number.

zero_pad_binary

public static String zero_pad_binary(long number,
                                     int digits)
Returns a zero-padded text string of a number in base-2 (binary) notation.

Parameters:
number - The number to format.
digits - The minimum number of digits to return.
Returns:
The zero-padded text representation of the number.

zero_pad_hex

public static String zero_pad_hex(long number,
                                  int digits)
Returns a zero-padded text string of a number in base-16 (hexadecimal) notation.

Parameters:
number - The number to format.
digits - The minimum number of digits to return.
Returns:
The zero-padded text representation of the number.

HiRISE

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