Observation
|
|
Observation
|
A Data_Component provides a common, virtual interface for all HiRISE Observation data blocks. More...
#include <Data_Component.hh>
Public Member Functions | |
| Data_Component (const char **names=NULL, unsigned int size=0, const Index *offsets=NULL, const Index indexed_arrays[][2]=NULL, Data_Order order=Data_Block::MSB) | |
| Constructs a Data_Component using component specifications. | |
| Data_Component (const Data_Component &component, bool data_duplicate=true) | |
| Copy constructor. | |
| Data_Component & | operator= (const Data_Component &component) |
| Assignment operator. | |
| virtual | ~Data_Component () |
| Destructor. | |
| virtual std::string | id () const |
| Gets the identification of this component. | |
| virtual const char * | name () const =0 |
| Gets the name of the component. | |
| const char * | name (Index element) const |
| Gets the name of a component Element. | |
| virtual u_int_32 | get (Index element, Index index=0) const |
| Gets a value from a data Element or array entry of the component. | |
| virtual Data_Component & | put (const u_int_32 value, Index element, Index index=0) |
| Puts a value into a data Element or array entry of the component. | |
| virtual idaeim::PVL::Aggregate * | PVL () const =0 |
| Produces an exhausitive PVL (Parameter Value Language) rendition of the component contents. | |
| virtual std::ostream & | print (std::ostream &stream=std::cout, bool verbose=false) const =0 |
| Prints a detailed description of the component structure and contents. | |
| std::ostream & | print_element (const Index element, int format=DECIMAL, std::ostream &stream=std::cout, int width=0) const |
| Prints an Element description. | |
| std::ostream & | print_element (const Index element, std::ostream &stream) const |
| Prints an Element description. | |
| std::ostream & | print_element_location (const Index element, std::ostream &stream=std::cout) const |
| Prints the location of an Element in the component. | |
| unsigned int | element_location_print_width (Index element) const |
| Gets the width of the Element location printing fields. | |
| unsigned int | name_field_width () const |
| Gets the width of the Element name printing field. | |
| Data_Component & | name_field_width (unsigned int width) |
| Sets the width of the Element name field for printing. | |
| virtual bool | is_valid () const =0 |
| Tests if the component data is valid. | |
| Data_Block & | data (void *const block) |
| Overrides the base Data_Block::data to reset Local_Data. | |
| Data_Block & | attach (void *const block, unsigned int size) |
| Attaches a new block of data to the component. | |
| Data_Component & | resize (unsigned int size) |
| Resizes the block of local data storage. | |
| unsigned char * | data () const |
| Gets a pointer to the current component storage. | |
| unsigned int | local_data () |
| Gets the size of the local data storage area. | |
| u_int_16 | internet_checksum () const |
| Calculates the Internet Checksum as per RFC 1071. | |
Public Attributes | |
| static const int | HEX = -1 |
| static const int | BOOLEAN = -2 |
Static Public Attributes | |
| static const char *const | ID = "UA::HiRISE::Data_Component (1.51 2020/05/14 22:48:28)" |
| Class identification name with source code version and date. | |
| static const int | DECIMAL = 0 |
| Format specifier. | |
| static const char | PATHNAME_DELIMITER = FILESYSTEM_PATHNAME_DELIMITER |
| Host filesystem pathname delimiter. | |
| static const int | UTC_SECONDS_PRECISION = SECONDS_PRECISION |
| UTC seconds precision (digits after the decimal point). | |
| static const char | SUBSECONDS_DELIMITER = ':' |
| Delimits subseconds from seconds in clock count representations. | |
| static const char *const | SPICE_METAKERNEL_VARIABLE |
| The name of the environment variable for the SPICE metakernel pathname. | |
| static const char *const | DEFAULT_SPICE_METAKERNEL |
| The default SPICE metakernal pathname. | |
| static const int | MRO_CLOCK_ID = MRO_CLOCK_NAIF_ID |
| The ID used by NAIF for specifying the MRO clock to CSPICE routines. | |
| static const char *const | INVALID_UTC_TIME = DEFAULT_INVALID_UTC_TIME |
A Data_Component provides a common, virtual interface for all HiRISE Observation data blocks.
It also subclasses the Instrument class which contains the HiRISE instrument constants, and the PIRL::Data_Block for host data order independence of the component's data store.
There will be an implmentation of this interface for each specific type of Data_Component that occurs in an Observation or data product.
1.38
| Data_Component | ( | const char ** | names = NULL, |
| unsigned int | size = 0, |
||
| const Index * | offsets = NULL, |
||
| const Index | indexed_arrays[][2] = NULL, |
||
| Data_Order | order = Data_Block::MSB |
||
| ) |
Constructs a Data_Component using component specifications.
Memory is allocated (size bytes) for the component's Data_Block, and initialized to 0. However, if size is 0 no memory is allocated; the Data_Block has NULL data. The memory is deleted when the component is destroyed or the data block is substituted by an external data block.
| names | The list of Element names in Element order. The names are expected to remain constant, so they are not copied. This list MUST be NULL terminated. |
| size | The size (bytes) of the component's data block. |
| offsets | The list of Element offsets in the data block in Element order. |
| indexed_arrays | The list of array Element entry counts using Element index references. Components with no array Elements will not provide this. |
| order | The order of data in data block. All HiRISE components are expected to be MSB ordered. |
| Data_Component | ( | const Data_Component & | component, |
| bool | data_duplicate = true |
||
| ) |
Copy constructor.
This component is a Data_Block copy which results in taking on all of the structural characteristics of the copied component.
The data content is copied only if data_duplicate is true. If data_duplicate is true, then memory for a copy of the source component data block is allocated, and the contents of the source data block is copied into this new data block. If data_duplicate is false, then the new data block will share the data storage memory of the source data block; the source data block retains ownership of the data storage.
| component | The component to be copied. |
| data_duplicate | true if the data content of the component is to be duplicated in the copy; false if the source component data is to be shared by this component. |
References Data_Component::data(), and Data_Block::size().
| ~Data_Component | ( | ) | [virtual] |
Destructor.
If the data block memory for the component has not been substituted by an external data block, it is deleted.
References Data_Component::data().
| Data_Component & operator= | ( | const Data_Component & | component ) |
Assignment operator.
Memory is allocated for a duplicate of the assigned data block storage. However, if the current data block is being locally managed (it has its own data storage) and at least as large as the assigned data block the current block is simply reused rather than replaced.
Also, a Data_Block assignment of the assigned compoent is applied to this component so it takes on all of the structural characteristics of assigned component.
| component | The component being assigned. |
References Data_Component::data(), and Data_Block::size().
Referenced by Science_Channel_Header::operator=(), MROSP_Header::operator=(), LUT::operator=(), Image_Line::operator=(), Gap_Map::operator=(), and Engineering_Header::operator=().
| string id | ( | ) | const [virtual] |
Gets the identification of this component.
The identification is the Data_Component class ID, the Instrument class ID and the Data_Block class ID each separated by a new-line. Each subclass of Data_Component is excpected to provided their own id method which provides their own class ID line preceeding this identification.
Reimplemented in Engineering_Header, Gap_Map, Image_Line, LUT, MROSP_Header, and Science_Channel_Header.
References Instrument::ID, and Data_Component::ID.
| virtual const char* name | ( | ) | const [pure virtual] |
Gets the name of the component.
Each subclass must provide their name method.
Implemented in Engineering_Header, Gap_Map, Image_Line, LUT, MROSP_Header, and Science_Channel_Header.
| const char * name | ( | Index | element ) | const |
Gets the name of a component Element.
| element | An Element Index of the component. |
| element | The Element Index. |
Gets a value from a data Element or array entry of the component.
Regardless of the precision (number of bits) of the component Element the value will always be cast up to a 32-bit integer.
| element | An Element Index of the component. |
| index | An array Elmenent entry index. |
Reimplemented from Data_Block.
Referenced by MROSP_Header::checksum(), MROSP_Header::data_amount(), Observation::data_ID(), Gap_Map::get(), Observation::line(), main(), MROSP_Header::pad_0(), MROSP_Header::pad_1(), MROSP_Header::protocol_ID(), Observation::reset_line(), MROSP_Header::sync(), MROSP_Header::transaction(), and MROSP_Header::transaction_ID().
| Data_Component & put | ( | const u_int_32 | value, |
| Index | element, | ||
| Index | index = 0 |
||
| ) | [virtual] |
Puts a value into a data Element or array entry of the component.
Regardless of the precision (number of bits) of the component Element the 32-bit integer value will always be cast appropriately.
| value | An unsigned integer value for the Element data. |
| element | An Element Index of the component. |
| index | An array Elmenent entry index. |
Referenced by main(), and Science_Channel_Header::print().
| virtual idaeim::PVL::Aggregate* PVL | ( | ) | const [pure virtual] |
Produces an exhausitive PVL (Parameter Value Language) rendition of the component contents.
Each Element has a parameter with its element name. All the paramters are contained in an Aggregate with the name of component.
Implemented in Engineering_Header, Gap_Map, Image_Line, LUT, MROSP_Header, and Science_Channel_Header.
| virtual std::ostream& print | ( | std::ostream & | stream = std::cout, |
| bool | verbose = false |
||
| ) | const [pure virtual] |
Prints a detailed description of the component structure and contents.
The listing is expected to start with a line containing the component's name preceeded by a ">>> " marker. In verbose mode this should be immediately followed by a line containing the component's class ID.
After a blank line, each Element of the component should be listed in Element order. Typically the print_element method is used to provide a single line description of an Element. For complex Elements (e.g. packed bit fields) additional lines describing each part of the element should be provided.
When not in verbose mode, inconsequential component Elements - typically padding - will not be included in the Element listings.
| stream | The ostream where the listing will be written. |
| verbose | true if the listing is to be verbose, otherwise some structural details will be omitted for easier human consumption. |
Implemented in Engineering_Header, Gap_Map, Image_Line, LUT, MROSP_Header, and Science_Channel_Header.
| ostream & print_element | ( | const Index | element, |
| int | format = DECIMAL, |
||
| std::ostream & | stream = std::cout, |
||
| int | width = 0 |
||
| ) | const |
Prints an Element description.
The description begins with its location listing. Then each Element value is listed, space separated, in the specified format (an array Element has more than one value).
| element | An Index of an Element in the component. |
| format | The selected format of the output. |
| stream | The ostream for output. |
| width | The width of the representation, as applicable. |
| std::ostream& print_element | ( | const Index | element, |
| std::ostream & | stream | ||
| ) | const [inline] |
Prints an Element description.
The Element is printed in DECIMAL format with 0 width.
| element | An Index of an Element in the component. |
| stream | The ostream for output. |
References Data_Component::DECIMAL, and Data_Component::print_element().
Referenced by Data_Component::print_element().
| ostream & print_element_location | ( | const Index | element, |
| std::ostream & | stream = std::cout |
||
| ) | const |
Prints the location of an Element in the component.
The format of the location listing is:
Element@Offset:Count*Size Name:
All parts of the location listing are right justified in their space padded fields.
| element | An Index of an Element in the component. |
| stream | The ostream where the listing will be written. |
| unsigned int element_location_print_width | ( | Index | element ) | const |
Gets the width of the Element location printing fields.
The width of the Element location field should be constant as determined by its fixed format. However, unusually large location data values or a name_field_width specification less than the length of the Element name will result in an actual field width that is longer than expected. This method prints the Element location and name to a string stream to determine its actual listing length.
| element | An Index of an Element in the component. |
| unsigned int name_field_width | ( | ) | const |
Gets the width of the Element name printing field.
| Data_Component & name_field_width | ( | unsigned int | width ) |
Sets the width of the Element name field for printing.
To provide a nicely formatted print listing, a consistent width for the Element name field is maintained as the Name_Field_Width data member of the Data_Component. When the object is constructed the maximum length of all Elements names is determined (and saved as the Max_Name_Length data member) and the Name_Field_Width value is initialzed with the value of Max_Name_Length. When an application is printing multiple Data_Component objects it may reset the Name_Field_Width to some other value; e.g. the maximum of all name_field_width values from each Data_Component.
If the width argument is 0 then the Name_Field_Width will be reset to the Max_Name_Length value.
| width | The character width for the Element name print field. If the value is 0 then the width will be reset to the Max_Name_Length value. |
| virtual bool is_valid | ( | ) | const [pure virtual] |
Tests if the component data is valid.
Implemented in Engineering_Header, Gap_Map, Image_Line, LUT, MROSP_Header, and Science_Channel_Header.
| Data_Block & data | ( | void *const | block ) | [virtual] |
Overrides the base Data_Block::data to reset Local_Data.
When a Data_Component is constructed it provides its own local data storage which is managed by the Data_Component. It may be appropriate to substitute an external data storage block that is managed externally.
When a new data block replaces a local block, the local block is deleted and the data storage is marked as being externally managed. If the new data block replaces an external block, the external block is not deleted; the external storage is the responsibility of the external owner.
N.B.: The contents of the previous data block are not copied into the new block.
Warning: It the responsibility of the new data block owner to ensure that it contains sufficient storage to accommodate all Elements of the component, as determined by the Data_Block::size method.
| block | The address of the new Data_Block storage. |
Reimplemented from Data_Block.
Referenced by Observation::components(), Data_Component::Data_Component(), Observation::line(), Line_Cache::Line_Cache(), Line_Cache::next_line(), and Data_Component::operator=().
| Data_Block & attach | ( | void *const | block, |
| unsigned int | size | ||
| ) |
Attaches a new block of data to the component.
The new data block is attached to this Data_Component: ownership of the new data block is passed to this Data_Component; the data block will be deleted when this Data_Component is destroyed.
Warning: The new data block must be dynamically allocated.
When a the new data block replaces a local block at a different address, the local block is deleted. N.B.: The contents of the previous data block are not copied into the new block.
| block | The address of the new Data_Block storage. |
| size | The size, in bytes, of the new data block. |
| length_error | If the size of the new block is insufficient to accommodate all Elements of the component, as determined by the Data_Block::size() method. |
References ID.
| Data_Component & resize | ( | unsigned int | size ) |
Resizes the block of local data storage.
If the component has its own local data or has no no data block and the requested new data block size is greater than the currently allocated amount, then local data block is reallocated at the larger size and the contents of the previous data block are copied into the new data block. N.B.: The size of the local data block is never decreased (use attach instead).
| size | The requested size of the local data block. |
References ID.
| unsigned char* data | ( | ) | const [inline] |
Gets a pointer to the current component storage.
Reimplemented from Data_Block.
Referenced by Data_Component::internet_checksum(), LUT::is_valid(), LUT::PVL(), LUT::PVL_PDS(), and Data_Component::~Data_Component().
| unsigned int local_data | ( | ) | [inline] |
Gets the size of the local data storage area.
| u_int_16 internet_checksum | ( | ) | const |
Calculates the Internet Checksum as per RFC 1071.
In outline, the Internet Checksum algorithm is very simple:
Adjacent octets to be checksummed are paired to form 16-bit integers, and the 1's complement sum of these 16-bit integers is formed.
To generate a checksum, the checksum field itself is cleared, the 16-bit 1's complement sum is computed over the octets concerned, and the 1's complement of this sum is placed in the checksum field.
To check a checksum, the 1's complement sum is computed over the same set of octets, including the checksum field. If the result is all 1 bits (-0 in 1's complement arithmetic), the check succeeds.
Suppose a checksum is to be computed over the sequence of octets A, B, C, D, ... , Y, Z. Using the notation [a,b] for the 16-bit integer a * 256 + b, where a and b are bytes, then the 16-bit 1's complement sum of these bytes is given by one of the following:
[A,B] +' [C,D] +' ... +' [Y,Z] [A,B] +' [C,D] +' ... +' [Z,0]
where +' indicates 1's complement addition. These cases correspond to an even or odd count of bytes, respectively.
On a 2's complement machine, the 1's complement sum must be computed by means of an "end around carry", i.e., any overflows from the most significant bits are added into the least significant bits.
For details see: http://www.faqs.org/rfcs/rfc1071.html
References Data_Component::data(), Data_Block::Get, and Data_Block::size().
Referenced by Science_Channel_Header::is_valid(), main(), Science_Channel_Header::print(), and MROSP_Header::print().
const char *const ID = "UA::HiRISE::Data_Component (1.51 2020/05/14 22:48:28)" [static] |
Class identification name with source code version and date.
Reimplemented from Instrument.
Reimplemented in Engineering_Header, FELICS_Line_Cache, Gap_Map, Image_Line, Line_Cache, LUT, MROSP_Header, and Science_Channel_Header.
Referenced by Data_Component::id(), and main().
const int DECIMAL = 0 [static] |
| const int BOOLEAN = -2 |
const char PATHNAME_DELIMITER = FILESYSTEM_PATHNAME_DELIMITER [static] |
Host filesystem pathname delimiter.
Referenced by main().
const int UTC_SECONDS_PRECISION = SECONDS_PRECISION [static] |
UTC seconds precision (digits after the decimal point).
const char SUBSECONDS_DELIMITER = ':' [static] |
Delimits subseconds from seconds in clock count representations.
const char *const SPICE_METAKERNEL_VARIABLE [static] |
The name of the environment variable for the SPICE metakernel pathname.
A pathname ust be provided to a SPICE metakernel that lists a SCLK kernal for the MRO spacecraft and a leap seconds kernel. The environment variable is tried first before the fallback default.
const char *const DEFAULT_SPICE_METAKERNEL [static] |
The default SPICE metakernal pathname.
const int MRO_CLOCK_ID = MRO_CLOCK_NAIF_ID [static] |
The ID used by NAIF for specifying the MRO clock to CSPICE routines.
const char *const INVALID_UTC_TIME = DEFAULT_INVALID_UTC_TIME [static] |
1.7.2