HiRISE
 Observation

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

Line_Cache Class Reference

A Line_Cache manages the data contents for an Image_Line. More...

#include <Line_Cache.hh>

Inheritance diagram for Line_Cache:
Inheritance graph
[legend]
Collaboration diagram for Line_Cache:
Collaboration graph
[legend]

List of all members.

Public Member Functions

 Line_Cache (Image_Line &image_line, std::istream &stream)
 Constructs a Line_Cache for an Image_Line bound to an istream.
virtual unsigned long long bytes_read () const
 Gets the total number of bytes read from the source stream.
unsigned long long source_bytes () const
 Gets the amount (bytes) of source data that has been used.
virtual bool compressed_data () const
 Tests if the image data is compressed.
virtual unsigned long long compressed_bytes () const
 Gets the amount (bytes) of compressed data that has been processed.
virtual unsigned long long decompressed_bytes () const
 Gets the amount (bytes) of decompressed data that has been generated.
unsigned int count () const
 Gets the current line count.
virtual Line_Cachesource (std::istream &stream)
 Sets the data source stream and resets the cache.
virtual std::istream & source () const
 Gets the data source stream.
std::string bad_line_description () const
 Gets the description of the bad line cause.
bool synchronization_lost ()
 Check for lost line synchronization.
bool next_line ()
 Gets the next line of image data into the Image_Line being managed.
virtual bool refill (unsigned long max_amount=(unsigned long)-1)
 Refills the cache storage from the data source stream.
virtual void reset ()
 Resets the cache to its empty state and the line structure to match the current structure of the managed line.

Static Public Attributes

static const char *const ID = "UA::HiRISE::Line_Cache (1.22 2010/11/25 04:20:56)"
 Class identification name with source code version and date.

Protected Member Functions

unsigned long long offset (char *location) const
 Gets the source offset location of a cache location.

Protected Attributes

Image_LineLine
 Image_Line being managed.
unsigned long long Data_Bytes
 The number of source data bytes used for line data.
unsigned int Line_Count
 The count of lines logically found so far.
unsigned int Next_Line_Number
 The number of the next line available in the cache.
bool Synchronization_Lost
 Has line synchronization been lost?
std::ostringstream Bad_Line_Description
 Message describing the reason for a repaired line.
std::string Next_Bad_Line_Description
 Message intended for the next line to be assembled.

Detailed Description

A Line_Cache manages the data contents for an Image_Line.

A Line_Cache uses an istream to provide the source of data for an Image_Line. In addition, the line data read from the stream is checked for structural integrity that is consistent with the characteracteristics of the Image_Line being managed. A broken line data sequence is replaced with line data having the correct structure, but filled with data gap values.

Though a Line_Cache is a subclass of Image_Line, the base object that is instantiated is not the Image_Line being managed. This is because the managed Image_Line itself makes the determination about what type of cache to instantiate based on an initial examination of the data from the stream. If a FELICS synchronization pattern is found then a FELICS_Line_Cache will be used (which is a subclass of Line_Cache) instead of a simple Line_Cache which is used when a normal line header synchronization pattern is found. The former type of cache overrides the cache content methods to decompress image data for use by the latter type of cache in the usual manner. The instantiated by Image_Line object is used both for its Image_Line manipulation methods, and to contain the gap filled replacement line data.

Image data structural integrity is determined by examing the data from the stream for the presence of a correct line header at the beginning of the line data and the presence of a correct line header (or Science Channel Header synchronization pattern, or end-of-file) at the expected location of the next line beginning. A correct line header contains all elements with the expected values. The failure to meet all the structural integrity criteria defines a broken line. For a broken line the data of the Image_Line being managed is assigned to the base Image_Line data with its gap filled values and line header set to contain the expected values. N.B.: Replacement data for broken lines will have a valid - not gap filled

Author:
Bradford Castalia, UA/PIRL, 12/04 1.7

Constructor & Destructor Documentation

Line_Cache ( Image_Line image_line,
std::istream &  stream 
)

Constructs a Line_Cache for an Image_Line bound to an istream.

Cache storage sufficient to hold at least 32 lines (of the largest size possible) is allocated.

References Data_Component::data().


Member Function Documentation

virtual unsigned long long bytes_read (  ) const [inline, virtual]

Gets the total number of bytes read from the source stream.

Returns:
The number of bytes read from the source.
See also:
refill()

Reimplemented from Cache.

Reimplemented in FELICS_Line_Cache.

Referenced by Image_Line::bytes_read(), and Line_Cache::offset().

unsigned long long source_bytes (  ) const [inline]

Gets the amount (bytes) of source data that has been used.

The amount of source data that was used to generate image lines, excluding any fill data, is returned. N.B.: This value will be less than or greater than the number of bytes read if the reconstruction of damaged image lines resulted in excess source data being dropped, or padded with gap fill values to replace missing data, respectively.

The count is reset to zero when the cache is reset.

Returns:
The number of source bytes used to generate image lines.

Reimplemented from Image_Line.

References Line_Cache::Data_Bytes.

Referenced by Image_Line::source_bytes().

virtual bool compressed_data (  ) const [inline, virtual]

Tests if the image data is compressed.

Returns:
Always returns false.

Reimplemented from Image_Line.

Reimplemented in FELICS_Line_Cache.

Referenced by Image_Line::compressed_data(), and Line_Cache::next_line().

virtual unsigned long long compressed_bytes (  ) const [inline, virtual]

Gets the amount (bytes) of compressed data that has been processed.

Returns:
Always returns zero.

Reimplemented from Image_Line.

Reimplemented in FELICS_Line_Cache.

Referenced by Image_Line::compressed_bytes().

virtual unsigned long long decompressed_bytes (  ) const [inline, virtual]

Gets the amount (bytes) of decompressed data that has been generated.

Returns:
Always returns zero.

Reimplemented from Image_Line.

Reimplemented in FELICS_Line_Cache.

Referenced by Image_Line::decompressed_bytes().

unsigned int count (  ) const [inline]

Gets the current line count.

The returned value is the logical line number of the current line data. This is the count of the number of lines that have been advanced since this Image_Line was constructed or the number of total_lines was set. This should be one more than the value of the line_number (if any lines have been read), but data loss or corruption during spacecraft data downlink may have invalidated some logical line data.

Returns:
The current line number.
See also:
total_lines(unsigned int)
next()

Reimplemented from Image_Line.

References Line_Cache::Line_Count.

Referenced by Image_Line::count().

Line_Cache & source ( std::istream &  stream ) [virtual]

Sets the data source stream and resets the cache.

In addition to setting the cache source, a reset is done.

Parameters:
streamThe istream to be used as the source of line data.
Returns:
This Line_Cache.
See also:
reset()

Reimplemented from Cache.

Reimplemented in FELICS_Line_Cache.

Referenced by Image_Line::source().

virtual std::istream& source (  ) const [inline, virtual]

Gets the data source stream.

Returns:
The istream used to refill the cache storage.

Reimplemented from Cache.

Reimplemented in FELICS_Line_Cache.

Referenced by FELICS_Line_Cache::source().

std::string bad_line_description (  ) const

Gets the description of the bad line cause.

Returns:
The bad line cause description string. This will be empty if the line is not marked as bad. Otherwise a multi-line description
  • with each line, including the last, ending with a new-line - is returned.

Reimplemented from Image_Line.

References Line_Cache::Bad_Line_Description.

Referenced by Image_Line::bad_line_description().

bool synchronization_lost (  ) [inline]

Check for lost line synchronization.

If, during acquisition of the next line, the line header synchronization is lost this condition will be flagged.

WARNING: Once line synchronization has been lost the source data stream will be left at a postion indeterminate with respect to the observation data structure. Further processing of the data stream without somehow reacquiring observation data structure synchronization will produce unpredictable results.

Returns:
true if line synchronization has been lost and further processing of the data source stream should be discontinued; false if line synchronization is still good.

Reimplemented from Image_Line.

References Line_Cache::Synchronization_Lost.

Referenced by Image_Line::synchronization_lost().

bool next_line (  )

Gets the next line of image data into the Image_Line being managed.

If the line count has reached the total number of lines expected for the Image_Line being managed nothing is done. This is the only case where false is returned.

If the next available line number is greater than the expected current line a patched line is generated for the managed line using gap values.

The cache storage is refilled as needed to contain enough data for a new line plus a following line header (plus a little extra for checking purposes). The refill is done indirectly using the cache pointer of the managed line. This ensures that the cache storage will be refilled using the cache mechanism chosen by the managed line.

For line 0 the initial line header at the beginning of the cache is checked and corrected as necessary. If a line header is found here that does not contain the expected channel number then an out_of_range exception is thrown.

If the current line is the last line, or insufficient data was available for a complete line, the remaining data from the cache is used. When insufficient data is available the managed line is patched.

If the line header for the next line is found at the expected location in the cache the managed line data is set to the location of the current line data in the cache storage.

If the line header for the next line is not found at the expected location the cache storage is searched for the next line header from the location just after the starting line header to a position slightly past (two line headers worth) where the next line header was expected. If one is not found then one is created at the expected location. If this location does not contain gap data then the header for the current line and newly created next line header are marked as being attached to a bad line. If the search found a line header then it is checked as being the expected following line header (or fixed if it fell on the edge of gap data). If this header is found to contain the line number for the currently expected line, then the position of the next line header is set to this line header and this method is called recursively to get the next line. If the line number in the header is less than the current line number, or the channel number it contains is not the expected channel number, then line synchronization has been lost and an out_of_range exception is thrown. Otherwise the managed line is patched with data from the current line header up to, but not including, the next line header.

The location of the line header following the current line header is set in the Cache as the next data location and the line counter is incremented before returning a true value.

N.B.: If line synchronization is lost as a result of finding a line header that does not contain the expected channel number all remaing lines will be gap filled.

Returns:
true if the next line of image data was obtained; false otherwise.
See also:
Image_Line::total_lines()
patch(char*, char*)
Image_Line::bad_line()
Image_Line::expected_channel()

References Cache::amount_consumed(), Cache::amount_free(), Cache::amount_remaining(), Image_Line::bad_line(), Line_Cache::Bad_Line_Description, Image_Line::cache(), Image_Line::channel(), Image_Line::Channel_Number, Line_Cache::compressed_data(), Data_Component::data(), Line_Cache::Data_Bytes, Cache::last(), Line_Cache::Line, Line_Cache::Line_Count, Image_Line::line_number(), Cache::next(), Line_Cache::Next_Bad_Line_Description, Line_Cache::Next_Line_Number, Image_Line::print(), Line_Cache::refill(), Data_Block::size(), Cache::state_report(), Image_Line::SYNC, Image_Line::sync(), Line_Cache::Synchronization_Lost, and Image_Line::Total_Lines.

Referenced by Image_Line::next().

bool refill ( unsigned long  max_amount = (unsigned long)-1 ) [virtual]

Refills the cache storage from the data source stream.

Parameters:
max_amountThe maximum amount of data to obtain.
Returns:
false if no more data is available; true otherwise. N.B.: If the cache storage is full no data will be read but the return value will still be true.

Reimplemented from Cache.

Reimplemented in FELICS_Line_Cache.

Referenced by Line_Cache::next_line().

void reset (  ) [virtual]

Resets the cache to its empty state and the line structure to match the current structure of the managed line.

The structure of the reserved line is reset to match the structure of the managed line, the line counters are reset to zero, and the cache storage is reset to its empty state.

Reimplemented from Cache.

Reimplemented in FELICS_Line_Cache.

References Line_Cache::Data_Bytes, Image_Line::expected_channel(), Line_Cache::Line, Line_Cache::Line_Count, Line_Cache::Next_Line_Number, Image_Line::pixel_bytes(), Image_Line::pixel_count(), and Image_Line::total_lines().

unsigned long long offset ( char *  location ) const [inline, protected]

Gets the source offset location of a cache location.

Parameters:
locationAn address (char*) of a cache location.
Returns:
The offset (bytes) of the location relative to the source location when the number of bytes read was last zero.

References Cache::amount_used(), Line_Cache::bytes_read(), and Cache::start().


Member Data Documentation

const char *const ID = "UA::HiRISE::Line_Cache (1.22 2010/11/25 04:20:56)" [static]

Class identification name with source code version and date.

Reimplemented from Cache.

Reimplemented in FELICS_Line_Cache.

Referenced by main().

Image_Line* Line [protected]

Image_Line being managed.

Referenced by Line_Cache::next_line(), and Line_Cache::reset().

unsigned long long Data_Bytes [protected]

The number of source data bytes used for line data.

See also:
source_bytes()

Referenced by Line_Cache::next_line(), Line_Cache::reset(), and Line_Cache::source_bytes().

unsigned int Line_Count [protected]

The count of lines logically found so far.

Referenced by Line_Cache::count(), Line_Cache::next_line(), and Line_Cache::reset().

unsigned int Next_Line_Number [protected]

The number of the next line available in the cache.

Referenced by Line_Cache::next_line(), and Line_Cache::reset().

bool Synchronization_Lost [protected]

Has line synchronization been lost?

Referenced by Line_Cache::next_line(), and Line_Cache::synchronization_lost().

std::ostringstream Bad_Line_Description [protected]

Message describing the reason for a repaired line.

If a delivered line has been repaired in any way there should be a bad line description for it. Before each line is assembled the bad line description is replaced with the Next_Bad_Line_Description which is then appended with any new messages.

Referenced by Line_Cache::bad_line_description(), and Line_Cache::next_line().

std::string Next_Bad_Line_Description [protected]

Message intended for the next line to be assembled.

During line data checking the line header for the next line is identified to ensure line structure integrity. Repairs to this next line header result in an explanation message that typically needs to be carried over and applied to the following line where it will be used to set the Bad_Line_Description.

Referenced by Line_Cache::next_line().


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