HiRISE
 libHiRISE

Public Types | Public Member Functions | Public Attributes | Static Public Attributes | Static Protected Attributes

Observation_ID Class Reference

Observation_ID encapsulates the HiRISE observation identification number. More...

#include <Observation_ID.hh>

Inheritance diagram for Observation_ID:
Inheritance graph
[legend]

List of all members.

Public Types

enum  Mission_Phase {
  INTEGRATION_AND_TESTING = 0,
  CALIBRATION,
  ATLO,
  KENNEDY_SPACE_CENTER,
  LAUNCH,
  CRUISE,
  APPROACH,
  AEROBRAKING,
  TRANSITION,
  PRIMARY_SCIENCE_PHASE,
  RELAY,
  EXTENDED_SCIENCE_PHASE,
  RESERVED_1,
  RESERVED_2,
  RESERVED_3,
  RESERVED_4,
  RESERVED_5,
  RESERVED_6,
  RESERVED_7,
  RESERVED_8,
  RESERVED_9,
  RESERVED_10,
  RESERVED_11,
  RESERVED_12,
  RESERVED_13,
  RESERVED_14,
  RESERVED_15,
  RESERVED_16,
  RESERVED_17,
  RESERVED_18,
  RESERVED_19,
  SVT,
  TOTAL_MISSION_PHASES
}
 

An enumeration for Mission_Phase.

More...

Public Member Functions

 Observation_ID (const u_int_32 id_value=DEFAULT_OBSERVATION_ID)
 Creates an Observation_ID from a numeric (decimal) representation.
 Observation_ID (const Mission_Phase mission_phase_value, const time_t seconds=-1)
 Creates a pre-orbit Observation_ID from a Mission_Phase and an integer Time value.
 Observation_ID (const Mission_Phase mission_phase_value, const unsigned int orbit_number_value, const unsigned int target_value)
 Creates an in-orbit Observation_ID from a Mission_Phase, an Orbit_Number, and a Target.
 Observation_ID (const std::string &id_text)
 Creates an Observation_ID from a string.
u_int_32 value () const
 Returns the Observation_ID's numeric value.
Observation_IDvalue (const u_int_32 id_value)
 Sets the Observation_ID's numeric value.
Observation_IDvalue (const std::string &id_text) throw (Invalid_Argument)
 Sets this Observation_ID's numeric value using a string representing a decimal unsigned 32-bit integer.
Observation_IDhex_value (const std::string &id_text) throw (Invalid_Argument)
 Sets this Observation_ID's numeric value using a string representing a hexadecimal unsigned 32-bit integer.
Mission_Phase mission_phase () const
 Returns the Observation_ID's Mission_Phase.
Observation_IDmission_phase (const Mission_Phase mission_phase_value) throw (Out_of_Range)
 Sets this Observation_ID's mission phase component.
Observation_IDmission_phase (const std::string &mission_phase_text) throw (Invalid_Argument)
 Parses an Observation_ID::Mission_Phase from a string.
Observation_IDmission_phase (time_t seconds) throw (Out_of_Range)
 Sets Observation_ID's mission phase component given the number of seconds since the Observation_ID::EPOCH.
Observation_IDmission_phase (const unsigned int orbit_number) throw (Out_of_Range)
 Sets Observation_ID's mission phase component given the orbit number.
time_t time () const throw (Invalid_Argument)
 Returns the Time value for a pre-orbit Observation_ID.
Observation_IDtime (const time_t seconds) throw (Invalid_Argument, Out_of_Range)
 Sets the Time value for a pre-orbit Observation_ID.
Observation_IDtime (const std::string &time_text, const std::string &time_text_format=STANDARD_TIME_TEXT_FORMAT) throw (Invalid_Argument, Out_of_Range)
 Parses an Observation_ID pre-orbit Time component from a string.
Observation_IDtime_now () throw (Invalid_Argument)
 Sets the Time value for a pre-orbit Observation_ID to the current time.
unsigned int orbit_number () const throw (Invalid_Argument)
 Returns the Orbit_Number for an in-orbit Observation ID.
Observation_IDorbit_number (const unsigned int orbit_number_value) throw (Invalid_Argument, Out_of_Range)
 Sets the Orbit_Number for an in-orbit Observation_ID.
Observation_IDorbit_number (const std::string &orbit_number_text) throw (Invalid_Argument, Out_of_Range)
 Sets the orbit number component for an in-orbit Observation_ID based on a text string.
unsigned int target () const throw (Invalid_Argument)
 Returns the Target for an in-orbit Observation_ID.
Observation_IDtarget (const unsigned int target_value) throw (Invalid_Argument, Out_of_Range)
 Sets the Target for an in-orbit Observation_ID.
Observation_IDtarget (const std::string &target_text) throw (Invalid_Argument, Out_of_Range)
 Sets the target component for an in-orbit Observation_ID based on a text string.
std::string text () const
 Returns the text representation of the Observation_ID.
Observation_IDtext (const std::string &id_text) throw (Invalid_Argument, Out_of_Range)
 Sets the Observation_ID based on a text string.
std::string parse (const std::string &id_text) throw (Invalid_Argument, Out_of_Range)
 Sets the Observation_ID based on a text string.
bool is_preorbit () const
 Returns true if the Observation_ID's Mission_Phase is a pre-orbit Mission_Phase.
std::ostream & print (std::ostream &stream=std::cout) const
 Prints the Observation_ID's text representation to an output stream.

Public Attributes

static const Mission_Phase DEFAULT_PREORBIT_PHASE = ATLO
 Default Mission_Phase for pre-orbit Observation_IDs.
static const Mission_Phase DEFAULT_INORBIT_PHASE = PRIMARY_SCIENCE_PHASE
 Default Mission_Phase for in-orbit Observation_IDs.
static const Mission_Phase DEFAULT_MISSION_PHASE = DEFAULT_PREORBIT_PHASE
 Default Mission_Phase for Observation_IDs for which the broader mission phase (pre-orbit versus in-orbit) is unknown.
static const u_int_32 INVALID_OBSERVATION_ID = 0
 Indicates an invalid Observation_ID.
static const unsigned int DEFAULT_ORBIT_NUMBER = 0
 Default value for Orbit_Number.
static const unsigned int DEFAULT_TARGET = 0
 Default value for Target.
static const char EXTENSION_DELIMITER = '.'
 Filename extension delimiter.
static const char * RSDS_TIME_TEXT_FORMAT = "%y.%j.%H%M%S"
static const char * JPL_TIME_TEXT_FORMAT = "%Y-%jT%H.%M.%S"
static const u_int_32 MISSION_PHASE_BIT_COUNT = 32 - MISSION_PHASE_START
 Number of bits in Mission_Phase.
static const u_int_32 MISSION_PHASE_MAX = (1 << MISSION_PHASE_BIT_COUNT) - 1
 Maximum value for Mission_Phase.
static const u_int_32 MISSION_PHASE_MASK = (MISSION_PHASE_MAX << MISSION_PHASE_START)
 Mission_Phase bitmask.
static const u_int_32 TIME_START = 0
 Starting bit for Time.
static const u_int_32 TIME_BIT_COUNT = MISSION_PHASE_START - TIME_START
 Number of bits in Time.
static const u_int_32 TIME_MAX = (1 << TIME_BIT_COUNT) - 1
 Maximum value for Time.
static const u_int_32 TIME_MASK = (TIME_MAX << TIME_START)
 Time bitmask.
static const u_int_32 ORBIT_NUMBER_START = 10
 Starting bit for Orbit_Number.
static const u_int_32 ORBIT_NUMBER_BIT_COUNT = MISSION_PHASE_START - ORBIT_NUMBER_START
 Number of bits in Orbit_Number.
static const u_int_32 ORBIT_NUMBER_MIN
 Minimum value for Orbit_Number.
static const u_int_32 ORBIT_NUMBER_MAX = (1 << ORBIT_NUMBER_BIT_COUNT) - 1
 Maximum value for Orbit_Number.
static const u_int_32 ORBIT_NUMBER_MASK = (ORBIT_NUMBER_MAX << ORBIT_NUMBER_START)
 Orbit_Number bitmask.
static const u_int_32 TARGET_START = 0
 Starting bit for Target.
static const u_int_32 TARGET_BIT_COUNT = ORBIT_NUMBER_START - TARGET_START
 Number of bits in Target.
static const u_int_32 TARGET_MAX = (1 << TARGET_BIT_COUNT) - 1
 Maximum value for Target.
static const u_int_32 TARGET_MASK = (TARGET_MAX << TARGET_START)
 Target bitmask.

Static Public Attributes

static const char * ID = "UA::HiRISE::Observation_ID (2.13 2016/04/14 18:31:57)"
 Class identification name with source code version and date.
static const int EPOCH = 1072915200
 Reference date for Observation_ID pre-orbit times.
static const Mission_Phase LAST_PREORBIT_PHASE = LAUNCH
 Marks the transition between pre-orbit and in-orbit Mission_Phase.
static const char * MISSION_PHASE_ABBREVIATION []
 The three-letter text representation for Mission_Phase.
static const char * MISSION_PHASE_NAME []
 Mission_Phase in a human-readable format.
static const int MISSION_PHASE_MAX_TIME []
 The times/dates associated with the mission phases.
static const unsigned int MISSION_PHASE_MAX_ORBIT []
 The orbit numbers associated with the mission phases.
static const u_int_32 DEFAULT_OBSERVATION_ID = 1
 Default numeric Observation_ID.
static const unsigned int DEFAULT_TIME = 0
 Default value for Time.
static const char TEXT_DELIMITER = '_'
 Text delimiter for text parsing.
static const char * STANDARD_TIME_TEXT_FORMAT = "%Y%m%dT%H%M%S"
static const u_int_32 MISSION_PHASE_START = 27
 Starting bit for Mission_Phase.

Static Protected Attributes

static const char * DELIMITER_PATTERN = "[_\\.\\-: ]"
 A set of delimiters.
static const char * REQUIRED_DELIMITER_PATTERN = "[_\\.\\-: ]{1}"
static const char * OPTIONAL_DELIMITER_PATTERN = "[_\\.\\-: ]{0,1}"
static const char * PREFIX_PATTERN = "(.*?)"
static const char * SUFFIX_PATTERN = "(.*?)"

Detailed Description

Observation_ID 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. An enumeration, Observation_ID::Mission_Phase, 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 ESL
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 Observation_ID::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.

Author:
Christian Schaller, UA/PIRL
Version:
2.6

Member Enumeration Documentation

An enumeration for Mission_Phase.

The Mission_Phase enumeration may be used as the index for the MISSION_PHASE_ABBREVIATION and MISSION_PHASE_NAME arrays.

See also:
LAST_PREORBIT_PHASE
DEFAULT_PREORBIT_PHASE
DEFAULT_INORBIT_PHASE
DEFAULT_MISSION_PHASE
Enumerator:
INTEGRATION_AND_TESTING 
CALIBRATION 
ATLO 
KENNEDY_SPACE_CENTER 
LAUNCH 
CRUISE 
APPROACH 
AEROBRAKING 
TRANSITION 
PRIMARY_SCIENCE_PHASE 
RELAY 
EXTENDED_SCIENCE_PHASE 
RESERVED_1 
RESERVED_2 
RESERVED_3 
RESERVED_4 
RESERVED_5 
RESERVED_6 
RESERVED_7 
RESERVED_8 
RESERVED_9 
RESERVED_10 
RESERVED_11 
RESERVED_12 
RESERVED_13 
RESERVED_14 
RESERVED_15 
RESERVED_16 
RESERVED_17 
RESERVED_18 
RESERVED_19 
SVT 
TOTAL_MISSION_PHASES 

Constructor & Destructor Documentation

Observation_ID ( const u_int_32  id_value = DEFAULT_OBSERVATION_ID ) [inline, explicit]

Creates an Observation_ID from a numeric (decimal) representation.

Parameters:
id_valuethe numeric value from which to create the new Observation_ID. Default: Observation_ID::DEFAULT_OBSERVATION_ID.
Observation_ID ( const Mission_Phase  mission_phase_value,
const time_t  seconds = -1 
)

Creates a pre-orbit Observation_ID from a Mission_Phase and an integer Time value.

This constructor will not throw. If invalid parameters are supplied, default values will be used instead.

The_mission_phase must be a pre-orbit phase. If it is not, Observation_ID::DEFAULT_PREORBIT_PHASE will be used instead.

Similarly, the_time must be less than or equal to Observation_ID::TIME_MAX. If it is not, Observation_ID::DEFAULT_TIME will be used instead. If the_time is negative, however, the current system clock time will be used.

Parameters:
mission_phase_valuethe pre-launch Mission_Phase for the new Observation_ID.
secondsthe Time value for the new Observation_ID. This value is the number of seconds since the HiRISE Epoch, Observation_ID::EPOCH. Default: -1 (use system clock time).
Observation_ID ( const Mission_Phase  mission_phase_value,
const unsigned int  orbit_number_value,
const unsigned int  target_value 
)

Creates an in-orbit Observation_ID from a Mission_Phase, an Orbit_Number, and a Target.

This constructor will not throw. If invalid parameters are supplied, default values will be used instead.

The_mission_phase must be an in-orbit phase. If it is not, Observation_ID::DEFAULT_INORBIT_PHASE will be used instead.

Likewise, the_orbit_number must be less than or equal to Observation_ID::ORBIT_NUMBER_MAX. If it is not, Observation_ID::DEFAULT_ORBIT_NUMBER will be used instead.

Similarly, if the_target is greater than Observation_ID::TARGET_MAX, Observation_ID::DEFAULT_TARGET will be used instead.

Parameters:
mission_phase_valuethe in-orbit Mission_Phase for the new Observation_ID.
orbit_number_valuethe Orbit_Number for the new Observation_ID.
target_valuethe Target for the new Observation_ID.

References Observation_ID::DEFAULT_INORBIT_PHASE, and Observation_ID::LAST_PREORBIT_PHASE.

Observation_ID ( const std::string &  id_text ) [explicit]

Creates an Observation_ID from a string.

If a valid observation ID cannot be parsed from the string, the object will be constructed with the value INVALID_OBSERVATION_ID. An exception will not be thrown.

Parameters:
id_textA string that contains a text representation of the Observation_ID.
See also:
text(const std::string)

Member Function Documentation

u_int_32 value (  ) const [inline]

Returns the Observation_ID's numeric value.

Returns:
the numeric value.

Referenced by main().

Observation_ID& value ( const u_int_32  id_value ) [inline]

Sets the Observation_ID's numeric value.

Parameters:
id_valuethe new numeric value of the Observation_ID.
Returns:
a reference back to the Observation_ID object.
Observation_ID & value ( const std::string &  id_text ) throw (Invalid_Argument)

Sets this Observation_ID's numeric value using a string representing a decimal unsigned 32-bit integer.

Parameters:
id_textThe text from which the Observation_ID's new value will be parsed. It must be an unsigned decimal 32-bit integer. It may be zero-padded.
Returns:
A reference back to this Observation_ID.
Exceptions:
Invalid_ArgumentIf no valid value can be parsed from the argument.

References ID.

Observation_ID & hex_value ( const std::string &  id_text ) throw (Invalid_Argument)

Sets this Observation_ID's numeric value using a string representing a hexadecimal unsigned 32-bit integer.

Parameters:
id_textThe text from which the Observation_ID's new value will be parsed. It must be an unsigned hexadecimal 32-bit integer. It may be zero-padded.
Returns:
A reference back to this Observation_ID.
Exceptions:
Invalid_ArgumentIf no valid value can be parsed from the argument.

References ID.

Observation_ID::Mission_Phase mission_phase (  ) const

Returns the Observation_ID's Mission_Phase.

Returns:
the Mission_Phase.

References Observation_ID::MISSION_PHASE_MASK, and Observation_ID::MISSION_PHASE_START.

Referenced by Observation_ID::is_preorbit(), and Observation_ID::text().

Observation_ID & mission_phase ( const Mission_Phase  mission_phase_value ) throw (Out_of_Range)

Sets this Observation_ID's mission phase component.

Parameters:
mission_phase_valueThe value of the new mission phase component for this Observation_ID.
Returns:
A reference back to this Observation_ID.
Exceptions:
Out_of_RangeIf the mission_phase_value is outside the allowable range for a Mission_Phase.
See also:
Observation_ID::Mission_Phase

References ID.

Observation_ID & mission_phase ( const std::string &  mission_phase_text ) throw (Invalid_Argument)

Parses an Observation_ID::Mission_Phase from a string.

This method compares the input mission_phase_text to the Observation_ID::MISSION_PHASE_NAME and Observation_ID::MISSION_PHASE_ABBREVIATION arrays. The comparison is done ignoring case and, for the latter comparison, ignoring delimiters as defined by Observation_ID::DELIMITER_PATTERN.

Parameters:
mission_phase_textThe text from which the mission phase will be parsed.
Returns:
A reference back to this Observation_ID.
Exceptions:
Invalid_ArgumentIf no valid mission phase could be parsed from mission_phase_text.

References ID.

Observation_ID & mission_phase ( time_t  seconds ) throw (Out_of_Range)

Sets Observation_ID's 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 Observation_ID::MISSION_PHASE_MAX_TIME array, using the first value 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:
secondsThe number of seconds since the Observation_ID::EPOCH.
Exceptions:
Out_of_RangeIf seconds represents a time greater than January 19, 2038, 03:14:07 UTC.

References ID.

Observation_ID & mission_phase ( const unsigned int  orbit_number ) throw (Out_of_Range)

Sets Observation_ID's mission phase component given the orbit number.

This method compares orbit_number to the different elements of the Observation_ID::MISSION_PHASE_MAX_ORBIT array, using the first value to which the orbit number is less than or equal to derive a mission phase.

Parameters:
orbit_numberThe orbit_number to use to return the mission_phase.
Exceptions:
Out_of_Range_ExceptionIf orbit_number is less than Observation_ID::ORBIT_NUMBER_MIN or greater than Observation_ID::ORBIT_NUMBER_MAX.

References ID.

time_t time (  ) const throw (Invalid_Argument)

Returns the Time value for a pre-orbit Observation_ID.

This value is the number of seconds since the HiRISE Observation_ID::EPOCH.

Returns:
the number of seconds since the HiRISE Observation_ID::EPOCH for the Observation_ID.
Exceptions:
Invalid_ArgumentIf this Observation_ID is not a pre-orbit ID.

References Observation_ID::ID, Observation_ID::is_preorbit(), Observation_ID::TIME_MASK, and Observation_ID::TIME_START.

Referenced by Observation_ID::text(), and Observation_ID::time_now().

Observation_ID & time ( const time_t  seconds ) throw (Invalid_Argument, Out_of_Range)

Sets the Time value for a pre-orbit Observation_ID.

This value must be expressed as the number of seconds since the HiRISE Observation_ID::EPOCH.

Parameters:
secondsthe number of seconds (time_t) since the HiRISE Observation_ID::EPOCH for the Observation_ID.
Returns:
a reference back to the Observation_ID object.
Exceptions:
Invalid_Argumentif the Observation_ID's Mission_Phase is not a pre-orbit Mission_Phase.
Out_of_Rangeif the_time is greater than Observation_ID::TIME_MAX.

References ID.

Observation_ID & time ( const std::string &  time_text,
const std::string &  time_text_format = STANDARD_TIME_TEXT_FORMAT 
) throw (Invalid_Argument, Out_of_Range)

Parses an Observation_ID pre-orbit Time component from a string.

This method uses the C-library strptime function to parse the time; the format is supplied in the second argument to this method, with a default value of Observation_ID::STANDARD_TIME_TEXT_FORMAT. The return value is an unsigned integer suitable for use in the Observation_ID::time(unsigned int) accessor method: it is the number of seconds since the HiRISE Observation_ID::EPOCH.

Parameters:
time_textThe text from which the time will be parsed.
time_text_formatThe format pattern used to parse time_text for a time. Default: Observation_ID::STANDARD_TIME_TEXT_FORMAT.
Returns:
A reference back to this Observation_ID.
Exceptions:
Invalid_ArgumentIf 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_RangeIf the parsed time component falls outside the range [Observation_ID::EPOCH, Observation_ID::EPOCH + Observation_ID::TIME_MAX].

References ID, UA::HiRISE::sync_to_day_of_year(), and UA::HiRISE::time_text().

Observation_ID & time_now (  ) throw (Invalid_Argument)

Sets the Time value for a pre-orbit Observation_ID to the current time.

The value is actually the number of seconds that have elapsed since the Observation_ID::EPOCH, which is constrained to be in the inclusive range [0, Observation_ID::TIME_MAX]. If the value is less than 0, the Time will be set to 0. If it is greater than TIME_MAX, it will be set to TIME_MAX.

Exceptions:
Invalid_ArgumentIf this Observation_ID is not a pre-orbit ID.

References Observation_ID::EPOCH, Observation_ID::ID, Observation_ID::is_preorbit(), Observation_ID::time(), Observation_ID::TIME_MASK, Observation_ID::TIME_MAX, and Observation_ID::TIME_START.

unsigned int orbit_number (  ) const throw (Invalid_Argument)

Returns the Orbit_Number for an in-orbit Observation ID.

Returns:
the Orbit_Number for the Observation_ID.
Exceptions:
Invalid_ArgumentIf this Observation_ID is not an in-orbit ID.

References Observation_ID::ID, Observation_ID::is_preorbit(), Observation_ID::ORBIT_NUMBER_MASK, and Observation_ID::ORBIT_NUMBER_START.

Referenced by Observation_ID::text().

Observation_ID & orbit_number ( const unsigned int  orbit_number_value ) throw (Invalid_Argument, Out_of_Range)

Sets the Orbit_Number for an in-orbit Observation_ID.

Parameters:
orbit_number_valuethe Orbit_Number for the Observation_ID.
Returns:
a reference back to the Observation_ID object.
Exceptions:
Invalid_ArgumentIf this Observation_ID is not an in-orbit ID.
Out_of_RangeIf orbit_number_value is greater than Observation_ID::ORBIT_NUMBER_MAX.

References ID.

Observation_ID & orbit_number ( const std::string &  orbit_number_text ) throw (Invalid_Argument, Out_of_Range)

Sets the orbit number component for an in-orbit Observation_ID based on a text string.

Parameters:
orbit_number_textThe text representation of the orbit number component for this Observation_ID.
Returns:
A reference back to this Observation_ID.
Exceptions:
Invalid_ArgumentIf this Observation_ID is not an in-orbit ID or if no orbit number can be parsed from orbit_number_text.
Out_of_RangeIf the orbit number parsed from orbit_number_text is greater than Observation_ID::ORBIT_NUMBER_MAX.

References ID.

unsigned int target (  ) const throw (Invalid_Argument)

Returns the Target for an in-orbit Observation_ID.

Values in the range [0, 719] represent the Martian central latitude of the observation to within a half-degree; divide the value by 2 to get the latitude, with 0 being the South pole on the ascending portion of the orbit.

Values outside this range represent off-planet targets. The exact meaning of the value is dependent on the particular orbit. It may refer to a star observation or an observation of Phobos or Deimos, for example.

Returns:
the Target for the Observation_ID.
Exceptions:
Invalid_ArgumentIf this Observation_ID is not an in-orbit ID.

References Observation_ID::ID, Observation_ID::is_preorbit(), Observation_ID::TARGET_MASK, and Observation_ID::TARGET_START.

Referenced by Observation_ID::text().

Observation_ID & target ( const unsigned int  target_value ) throw (Invalid_Argument, Out_of_Range)

Sets the Target for an in-orbit Observation_ID.

Parameters:
target_valuethe Target for the Observation_ID.
Returns:
a reference back to the Observation_ID object.
Exceptions:
Invalid_ArgumentIf this Observation_ID is not an in-orbit ID.
Out_of_RangeIf target_value is greater than Observation_ID::TARGET_MAX.

References ID.

Observation_ID & target ( const std::string &  target_text ) throw (Invalid_Argument, Out_of_Range)

Sets the target component for an in-orbit Observation_ID based on a text string.

The string is assumed to be in the form of the text representation of the target component.

Parameters:
target_textThe text representation of the orbit number component for this Observation_ID.
Returns:
A reference back to this Observation_ID.
Exceptions:
Invalid_ArgumentIf this Observation_ID is not an in-orbit ID or if no target can be parsed from the_orbit_number.
Out_of_RangeIf the parsed value for the target component does not map to a valid target component numeric value.

References ID.

std::string text (  ) const
Observation_ID & text ( const std::string &  id_text ) throw (Invalid_Argument, Out_of_Range)

Sets the Observation_ID based on a text string.

This method calls the Observation_ID::parse(const std::string&) method, which does all of the work. While the latter method returns a string, however, this method returns a reference back to this Observation_ID object, allowing for method chaining.

Parameters:
id_textthe text string containing a representation of the Observation_ID or containing enough information to create one.
Returns:
a reference back to this Observation_ID.
Exceptions:
Invalid_Argumentif....
Out_of_Rangeif....
See also:
Observation_ID::parse(const std::string&)

Reimplemented in CCD_ID, and Channel_ID.

std::string parse ( const std::string &  id_text ) throw (Invalid_Argument, Out_of_Range)

Sets the Observation_ID based on a text string.

This method returns a new string containing the text that was not used in the determination of the Observation_ID. This text can be used by subclasses to determine other related information, such as the channel number in the case of the Channel_ID::parse(const std::string&) method.

This method makes a number of attempts at identifying an Observation_ID in its input parameter, in the following manner:

1. The text representation of a pre-orbit Observation_ID is searched for in id_text. If found, it is used to set the Observation_ID and the text following the ID is returned.

2. The text representation of an in-orbit Observation_ID is search for in id_text. If found, it is used to set the Observation_ID and the text following the ID is returned.

3. The id_text is tried as an RSDS test venue filename. If it appears to be one, the test_id portion of the filename is used to set the Observation_ID. The CPMM/channel information, the gap indicator, the version identifier, and the filename extension are returned.

4. The id_text is tried as an RSDS operations venue filename. If it appears to be one, the hex Observation_ID portion of the filename is used to set the Observation_ID. The CPMM/channel information, the gap indicator, the version identifier, and the filename extension are returned.

5. A JPL-style date/time code is searched for in the id_text. The JPL-style code is of the form YYYY-DDDTHH.MM.SS (four-digit year, three digit, zero-padded day-of-year, the capital letter "T," a two-digit hour, a two-digit minutes, and a two-digit seconds, assumed to be in the UTC time reference). If such a code is found in id_text, it used to set the Observation_ID. All text not part of the JPL code is returned.

6. An RSDS-style date/time code, which is the RSDS test venue test_id, is searched for in the text. If found, it is used to set the Observation_ID. All text not part of the RSDS date/time code is returned.

7. Finally, an 8-digit hexadecimal number is searched for in the id_text. If found, it is used to set the Observation_ID. All text not part of the matched hex is returned. Note that the first sequence of characters that looks like an 8-digit hex number will be used if found.

If none of the above tests works, an Invalid_Argument exception is thrown.

Parameters:
id_textthe text string containing a representation of the Observation_ID or containing enough information to create one.
Returns:
This text used to set the value. This will be empty if no valid text was found.
Exceptions:
Invalid_Argumentif ....
Out_of_Rangeif ....

Reimplemented in CCD_ID, and Channel_ID.

References ID.

Referenced by CCD_ID::parse().

bool is_preorbit (  ) const [inline]

Returns true if the Observation_ID's Mission_Phase is a pre-orbit Mission_Phase.

Returns:
true if the Mission_Phase is pre-orbit, false if it is not.

References Observation_ID::LAST_PREORBIT_PHASE, and Observation_ID::mission_phase().

Referenced by Observation_ID::orbit_number(), Observation_ID::target(), Observation_ID::text(), Observation_ID::time(), and Observation_ID::time_now().

std::ostream & print ( std::ostream &  stream = std::cout ) const

Prints the Observation_ID's text representation to an output stream.

Parameters:
streamthe output stream. Default: std::cout.
Returns:
a reference back to the output stream.

Reimplemented in CCD_ID, and Channel_ID.


Member Data Documentation

const char * ID = "UA::HiRISE::Observation_ID (2.13 2016/04/14 18:31:57)" [static]

Class identification name with source code version and date.

Reimplemented in CCD_ID, and Channel_ID.

Referenced by Observation_ID::orbit_number(), Observation_ID::target(), Observation_ID::time(), and Observation_ID::time_now().

const int EPOCH = 1072915200 [static]

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.

Referenced by Observation_ID::time_now().

Marks the transition between pre-orbit and in-orbit Mission_Phase.

Referenced by Observation_ID::is_preorbit(), and Observation_ID::Observation_ID().

Default Mission_Phase for pre-orbit Observation_IDs.

Default Mission_Phase for in-orbit Observation_IDs.

Referenced by Observation_ID::Observation_ID().

Default Mission_Phase for Observation_IDs for which the broader mission phase (pre-orbit versus in-orbit) is unknown.

const char * MISSION_PHASE_ABBREVIATION [static]
Initial value:
    {
        "INT",  
        "CAL",  
        "ATL",  
        "KSC",  
        "LAU",  
        "CRU",  
        "APR",  
        "AEB",  
        "TRA",  
        "PSP",  
        "REL",  
        "ESP",  
        "R01",  
        "R02",  
        "R03",  
        "R04",  
        "R05",  
        "R06",  
        "R07",  
        "R08",  
        "R09",  
        "R10",  
        "R11",  
        "R12",  
        "R13",  
        "R14",  
        "R15",  
        "R16",  
        "R17",  
        "R18",  
        "R19",  
        "SVT"   
    }

The three-letter text representation for Mission_Phase.

Referenced by Observation_ID::text().

const char * MISSION_PHASE_NAME [static]
Initial value:
    {
        "Integration and Testing",
        "Calibration",
        "ATLO",
        "Kennedy Space Center",
        "Launch",
        "Cruise",
        "Approach",
        "Aerobraking",
        "Transition",
        "Primary Science Phase",
        "Relay",
        "Extended Science Phase",
        "Reserved 1",
        "Reserved 2",
        "Reserved 3",
        "Reserved 4",
        "Reserved 5",
        "Reserved 6",
        "Reserved 7",
        "Reserved 8",
        "Reserved 9",
        "Reserved 10",
        "Reserved 11",
        "Reserved 12",
        "Reserved 13",
        "Reserved 14",
        "Reserved 15",
        "Reserved 16",
        "Reserved 17",
        "Reserved 18",
        "Reserved 19",
        "Sequence Verification Tests"
    }

Mission_Phase in a human-readable format.

These 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.

const int MISSION_PHASE_MAX_TIME [static]
Initial value:
    {
          28684800, 
          29289600, 
          44582400, 
          50457600, 
          51580800, 
          63158400, 
          68256000, 
          84153600, 
          90028800, 
         156816000, 
         156816000, 
         220838400, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447, 
        1074568447  
    }

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.

const unsigned int MISSION_PHASE_MAX_ORBIT [static]
Initial value:

The orbit numbers associated with the mission phases.

These orbits are indexed by Mission_Phase.

const u_int_32 DEFAULT_OBSERVATION_ID = 1 [static]

Default numeric Observation_ID.

Indicates an invalid Observation_ID.

const u_int_32 DEFAULT_TIME = 0 [static]

Default value for Time.

Default value for Orbit_Number.

Default value for Target.

const char TEXT_DELIMITER = '_' [static]

Text delimiter for text parsing.

Referenced by Observation_ID::text(), Channel_ID::text(), and CCD_ID::text().

const char EXTENSION_DELIMITER = '.'

Filename extension delimiter.

const char * STANDARD_TIME_TEXT_FORMAT = "%Y%m%dT%H%M%S" [static]
const char * RSDS_TIME_TEXT_FORMAT = "%y.%j.%H%M%S"
const char * JPL_TIME_TEXT_FORMAT = "%Y-%jT%H.%M.%S"
const u_int_32 MISSION_PHASE_START = 27 [static]

Starting bit for Mission_Phase.

Referenced by Observation_ID::mission_phase().

Number of bits in Mission_Phase.

Maximum value for Mission_Phase.

Mission_Phase bitmask.

Referenced by Observation_ID::mission_phase().

const u_int_32 TIME_START = 0

Starting bit for Time.

Referenced by Observation_ID::time(), and Observation_ID::time_now().

Number of bits in Time.

const u_int_32 TIME_MAX = (1 << TIME_BIT_COUNT) - 1

Maximum value for Time.

Referenced by Observation_ID::time_now().

Time bitmask.

Referenced by Observation_ID::time(), and Observation_ID::time_now().

Starting bit for Orbit_Number.

Referenced by Observation_ID::orbit_number().

Number of bits in Orbit_Number.

Minimum value for Orbit_Number.

Maximum value for Orbit_Number.

Orbit_Number bitmask.

Referenced by Observation_ID::orbit_number().

Starting bit for Target.

Referenced by Observation_ID::target().

Number of bits in Target.

const u_int_32 TARGET_MAX = (1 << TARGET_BIT_COUNT) - 1

Maximum value for Target.

Target bitmask.

Referenced by Observation_ID::target().

const char * DELIMITER_PATTERN = "[_\\.\\-: ]" [static, protected]

A set of delimiters.

const char * REQUIRED_DELIMITER_PATTERN = "[_\\.\\-: ]{1}" [static, protected]
const char * OPTIONAL_DELIMITER_PATTERN = "[_\\.\\-: ]{0,1}" [static, protected]
const char * PREFIX_PATTERN = "(.*?)" [static, protected]
const char * SUFFIX_PATTERN = "(.*?)" [static, protected]

The documentation for this class was generated from the following files: