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

#include <Observation_ID.hh>

Inheritance diagram for Observation_ID:

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_ID &	value (const u_int_32 id_value)
	Sets the Observation_ID's numeric value.
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.
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.
Mission_Phase	mission_phase () const
	Returns the Observation_ID's Mission_Phase.
Observation_ID &	mission_phase (const Mission_Phase mission_phase_value) throw (Out_of_Range)
	Sets this Observation_ID's mission phase component.
Observation_ID &	mission_phase (const std::string &mission_phase_text) throw (Invalid_Argument)
	Parses an Observation_ID::Mission_Phase from a string.
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.
Observation_ID &	mission_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_ID &	time (const time_t seconds) throw (Invalid_Argument, Out_of_Range)
	Sets the Time value for a pre-orbit Observation_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.
Observation_ID &	time_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_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.
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.
unsigned int	target () const throw (Invalid_Argument)
	Returns the Target for an in-orbit Observation_ID.
Observation_ID &	target (const unsigned int target_value) throw (Invalid_Argument, Out_of_Range)
	Sets the Target for an in-orbit Observation_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.
std::string	text () const
	Returns the text representation of the Observation_ID.
Observation_ID &	text (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.15 2020/05/21 17:36:23)"
	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

PPP - Mission_Phase text
yymmdd_HHMMSS - Time
- yyyy - year
- mm - month
- dd - day of month
- T - (marker)
- HH - hour (24-hour clock)
- MM - minute
- SS - second

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

PPP - Mission_Phase text
NNNNNN - Orbit_Number (zero-padded)
TTTT - Target (zero-padded)

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

Member Enumeration Documentation

enum Mission_Phase

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_value the 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_value	the pre-launch Mission_Phase for the new Observation_ID.
seconds	the 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_value	the in-orbit Mission_Phase for the new Observation_ID.
orbit_number_value	the Orbit_Number for the new Observation_ID.
target_value	the 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_text A 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_value the 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_text The 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_Argument If 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_text The 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_Argument If 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_value The value of the new mission phase component for this Observation_ID.

Returns:: A reference back to this Observation_ID.

Exceptions:

Out_of_Range If 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_text The text from which the mission phase will be parsed.

Returns:: A reference back to this Observation_ID.

Exceptions:

Invalid_Argument If 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:

seconds The number of seconds since the Observation_ID::EPOCH.

Exceptions:

Out_of_Range If 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_number The orbit_number to use to return the mission_phase.

Exceptions:

Out_of_Range_Exception If 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_Argument If 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:

seconds the 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_Argument	if the Observation_ID's Mission_Phase is not a pre-orbit Mission_Phase.
Out_of_Range	if 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_text	The text from which the time will be parsed.
time_text_format	The 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_Argument	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	If 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_Argument If 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_Argument If 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_value the Orbit_Number for the Observation_ID.

Returns:: a reference back to the Observation_ID object.

Exceptions:

Invalid_Argument	If this Observation_ID is not an in-orbit ID.
Out_of_Range	If 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_text The text representation of the orbit number component for this Observation_ID.

Returns:: A reference back to this Observation_ID.

Exceptions:

Invalid_Argument	If this Observation_ID is not an in-orbit ID or if no orbit number can be parsed from orbit_number_text.
Out_of_Range	If 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_Argument If 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_value the Target for the Observation_ID.

Returns:: a reference back to the Observation_ID object.

Exceptions:

Invalid_Argument	If this Observation_ID is not an in-orbit ID.
Out_of_Range	If 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_text The text representation of the orbit number component for this Observation_ID.

Returns:: A reference back to this Observation_ID.

Exceptions:

Invalid_Argument	If this Observation_ID is not an in-orbit ID or if no target can be parsed from the_orbit_number.
Out_of_Range	If the parsed value for the target component does not map to a valid target component numeric value.

References ID.

std::string text ( ) const

Returns the text representation of the Observation_ID.

Returns:: the text representation of the Observation_ID.

Reimplemented in CCD_ID, and Channel_ID.

References Observation_ID::is_preorbit(), Observation_ID::mission_phase(), Observation_ID::MISSION_PHASE_ABBREVIATION, Observation_ID::orbit_number(), Observation_ID::target(), Observation_ID::TEXT_DELIMITER, Observation_ID::time(), and UA::HiRISE::time_text().

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_text the 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_Argument	if....
Out_of_Range	if....

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_text the 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_Argument	if ....
Out_of_Range	if ....

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:

stream the 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.15 2020/05/21 17:36:23)" [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().

const Observation_ID::Mission_Phase LAST_PREORBIT_PHASE = LAUNCH [static]

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

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

const Observation_ID::Mission_Phase DEFAULT_PREORBIT_PHASE = ATLO

Default Mission_Phase for pre-orbit Observation_IDs.

const Observation_ID::Mission_Phase DEFAULT_INORBIT_PHASE = PRIMARY_SCIENCE_PHASE

Default Mission_Phase for in-orbit Observation_IDs.

Referenced by Observation_ID::Observation_ID().

const Observation_ID::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.

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:

    {
                       0,   
                       0,   
                       0,   
                       0,   
                       0,   
                       0,   
                       0,   
                       0,   
                    1000,   
                   11248,   
                   11248,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX,   
        ORBIT_NUMBER_MAX    
    }