HiRISE
 Observation

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

Image_Line Class Reference

An Image_Line contains a cache of observation channel image pixel data. More...

#include <Image_Line.hh>

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

List of all members.

Public Types

enum  Elements {
  Sync,
  Channel,
  Line_Number,
  Buffer_Pixels,
  Image_Pixels,
  Black_Pixels,
  Virtual_Pixels,
  Total_Elements
}
 

An Element refers to a data containing constituent of a component.

More...
enum  Sync_Type {
  No_Sync_Type,
  Line_Header_Sync_Type,
  FELICS_Sync_Type
}
 

Possible types of sync patterns.

More...

Public Member Functions

 Image_Line ()
 Constructs a default Image_Line.
 Image_Line (unsigned int bytes_per_pixel, unsigned int total_pixels, unsigned int total_lines=0, unsigned int channel_number=CCD_UNKNOWN, std::istream *stream=NULL)
 Constructs an Image_Line of a specified line length and pixel size.
 Image_Line (const Image_Line &component, bool duplicate=true)
 Copy constructor.
Image_Lineoperator= (const Image_Line &component)
 Assigns another Image_Line to this one.
virtual ~Image_Line ()
 Destructor.
std::string id () const
 Provides the class ID on a line followed by the base Data_Component::id.
const char * name () const
 Gets the NAME of this class.
u_int_32 sync () const
 Gets the extended Sync Element value.
Image_Linesync (u_int_32 value)
 Sets the extended Sync Element value.
u_int_32 channel () const
 Gets the Channel Element channel number.
Image_Linechannel (u_int_32 channel_number)
 Sets the Channel Element channel number.
u_int_32 expected_channel () const
 Gets the expected channel number for the line header.
Image_Lineexpected_channel (u_int_32 channel_number)
 Sets the expected channel number for the line header.
u_int_32 line_number () const
 Gets the Line_Number Element value.
Image_Lineline_number (u_int_32 line)
 Sets the Line_Number Element value.
bool bad_line () const
 Tests if the bad line flag is set.
Image_Linebad_line (bool state)
 Sets or clears the bad line flag.
std::string bad_line_description () const
 Gets the description of the bad line cause.
Pixel_type pixel (Index index) const
 Gets a pixel value.
Pixel_type operator[] (Index index) const
 Gets a pixel value.
void pixel (Index index, Pixel_type value)
 Sets a pixel value.
Pixel_type buffer_pixel (Index index) const
 Gets a Buffer_Pixels Element value.
void buffer_pixel (Index index, Pixel_type value)
 Sets a Buffer_Pixels Element value.
Pixel_type image_pixel (Index index) const
 Gets an Image_Pixels Element value.
void image_pixel (Index index, Pixel_type value)
 Sets an Image_Pixels Element value.
Pixel_type black_pixel (Index index) const
 Gets a Black_Pixels Element value.
void black_pixel (Index index, Pixel_type value)
 Sets a Black_Pixels Element value.
Pixel_type virtual_pixel (Index index) const
 Gets a Virtual_Pixels Element value.
void virtual_pixel (Index index, Pixel_type value)
 Sets a Virtual_Pixels Element value.
unsigned int pixel_count () const
 Gets the total number of pixels in the line.
Image_Linepixel_count (unsigned int total_pixels)
 Sets the total number of pixels in the line.
unsigned int pixel_bytes () const
 Gets the number of bytes per pixel.
Image_Linepixel_bytes (unsigned int bytes_per_pixel)
 Sets the number of bytes per pixel.
unsigned int total_lines () const
 Gets the total number of image lines in the channel data set.
Image_Linetotal_lines (unsigned int lines)
 Sets the total number of image lines in the channel data set.
void mirror ()
 Mirrors the order of all pixels.
Image_Linelookup (const LUT &lut)
 Applies a LUT mapping to all pixel values.
Image_Linepukool (Pixel_type *table)
 Applies a "reverse" table mapping to all pixel values.
std::istream & source () const
 Gets the istream being used as the source of line data.
Image_Linesource (std::istream &stream)
 Sets the input stream to be used as the source of line data.
bool next ()
 Gets the next image line.
unsigned int count () const
 Gets the current line count.
unsigned long long bytes_read () const
 Gets the number of bytes read from the data source.
unsigned long long source_bytes () const
 Gets the amount (bytes) of source data that has been used.
bool compressed_data () const
 Indicates if the source line data was FELICS compressed.
unsigned long long compressed_bytes () const
 Gets the amount (bytes) of compressed data that has been processed.
unsigned long long decompressed_bytes () const
 Gets the amount (bytes) of decompressed data that has been generated.
Line_Cachecache ()
 Gets the line's data management cache object.
bool synchronization_lost ()
 Check for lost line synchronization.
std::ostream & print (std::ostream &stream=std::cout, bool verbose=false) const
 Prints the component structure and contents.
unsigned int width () const
 Gets the print listing width.
Image_Linewidth (unsigned int groups)
 Sets the print listing width.
idaeim::PVL::AggregatePVL () const
 Produces a PVL rendition of the component.
idaeim::PVL::AggregatePVL_description () const
 Produces a PVL description of the observation image data layout for a PDS label.
bool is_valid () const
 Tests if the component data is valid.

Static Public Member Functions

static unsigned int calibration_lines ()
 Gets the number of image lines designated as calibration data.
static void calibration_lines (unsigned int lines)
 Sets the number of image lines designated as calibration data.
static bool is_sync (void *data_at)
 Tests if some data contains a line header sync pattern.
static Sync_Type next_sync (std::istream &stream)
 Searches an istream for an image data synchronization pattern.

Static Public Attributes

static const char *const ID = "UA::HiRISE::Image_Line (1.42 2010/11/25 02:51:13)"
 Class identification name with source code version and date.
static const char *const NAME = "Image Line"
 The component name.
static const char * NAMES []
 The name of each Element.
static const unsigned int LINE_HEADER_BYTES = 6
 The number of bytes in the line header section.
static const unsigned int BUFFER_PIXELS_COUNT = 12
 The number of buffer pixels.
static const unsigned int BLACK_PIXELS_COUNT = 16
 The number of black pixels.
static const unsigned int MAX_VIRTUAL_PIXELS_COUNT = MAX_VIRTUAL_PIXELS
 The maximum number of allowable virtual pixels.
static const unsigned int MAX_PIXELS_PER_LINE
 The maximum number of pixels allowed.
static const unsigned int DEFAULT_CALIBRATION_LINES = CALIBRATION_LINES
 The default number of calibration lines at the beginning of the observation channel data.
static const Index MAX_COMPONENT_BYTES
 Total maximum number of bytes in the Data_Block.
static const Index OFFSETS_TEMPLATE []
 Data_Block data storage address offset template for each Element.
static const Index ARRAY_COUNTS_TEMPLATE [][2]
 Data_Block array element value counts each keyed to an Element Index.
static const u_int_32 SYNC = 0xFF00E000
 Expected Sync Element value after extension.
static const u_int_8 SYNC_3 = 0xFF
 Expected Sync Element MSB (byte 3) value.
static const u_int_8 SYNC_2 = 0x00
 Expected Sync Element MSB+1 (byte 2) value.
static const u_int_8 SYNC_1_BIT_MASK = 0xE0
 Bit mask for the Sync Element extension field of the Channel Element.
static const u_int_8 CHANNEL_BIT_MASK = 0x1F
 Bit mask for channel number field of the Channel Element.
static const u_int_32 LINE_NUMBER_MASK = 0x007FFFFF
 Bit mask for the line number field of the Line_Number Element.
static const char * Sync_Type_Names []
 Sync_Type names.
static const unsigned int DEFAULT_WIDTH = LINE_PRINT_GROUPS_WIDTH
 The default width, in pixel groups, of a print listing.
static unsigned int Calibration_Lines = CALIBRATION_LINES
 Number of image lines at the beginning of the image data to be designated as calibration data.

Protected Attributes

unsigned int Pixels_per_Line
 Total pixels in a line.
unsigned int Bytes_per_Pixel
 Bytes per pixel.
unsigned int Total_Lines
 Total number of lines expected.
unsigned int Channel_Number
 Expected channel number.
Line_CacheData_Cache
 Line data cache.
unsigned int Width
 Width of listing (pixel groups).

Detailed Description

An Image_Line contains a cache of observation channel image pixel data.

This Data_Component is the last in the observation channel data stream. The component contains a cache of image line data that was read or written. Methods are provided to advance sequentially through the image data lines available from a source data stream by reading data into the cache as needed. Unlike the other components of a HiRISE observation, an Image_Line does not have a fixed size, so its structure is dynamically sized when it is constructed or characteristics of its structure that affect its size are altered. The number of bytes per pixel and the number of pixels per line are the critical size determining characteristics. So while the component data layout always has the same relative relationships, these relationships are relative to these critical characteristics.

For details consult the "HiRISE Command and Telemetry Handbook" (http://hirise.lpl.arizona.edu/team_site/instrument/Command_and_Telemetry_Handbook/).

Header data block layout:

	Offset  Size  Description
	------  ----  -----------
	     0     2  Sync pattern (0xFF00)
	     2     1  Channel number
	                Bits   Description
	                -----  -----------
                    0 - 4  Channel number
                    5 - 7  Sync pattern extension (0xE0)
         3     3  Line number
	                Bit 23 is the bad line flag (1 == bad line) 
         6  12*S  Buffer pixels
	   IPO   L*S  Image pixels
	   BPO  16*S  Black pixels
	   VPO   V*S  Virtual pixels

The first 6 bytes contain the line header data.

S is the size of pixel in bytes. This will be either 1 or 2.

IPO is the image pixels offset: the line header size (6) plus the number of buffer pixel bytes (12*S).

L is the length, in pixels, of an image line (only those pixels exposed to the observation scene). This will be a maximum of 1024.

BPO is the black pixels offset: the line header size (6), plus the number of buffer pixels bytes (12*S), plus the number of image pixel bytes (L*S).

VPO is the virtual pixels offset: the line header size (6), plus the number of buffer pixels bytes (12*S), plus the number of image pixel bytes (L*S), plus the number of black pixel bytes (16*S).

V is the number of virtual pixels. Virtual pixels should only occur in special test data files produced by the instrument manufacturer; normally this is 0.

N.B.: Data_Block values are MSB ordered.

Author:
Bradford Castalia, UA/PIRL, 12/03 1.36

Member Enumeration Documentation

enum Elements

An Element refers to a data containing constituent of a component.

Each named Element is an Index into various data sets that define the attributes of a component; including their NAMES, data storage address OFFSETS_TEMPLATE, and number of array element values. It is the key Index argument of the data access methods.

See also:
Data_Block
Enumerator:
Sync 
Channel 
Line_Number 
Buffer_Pixels 
Image_Pixels 
Black_Pixels 
Virtual_Pixels 
Total_Elements 
enum Sync_Type

Possible types of sync patterns.

The types of sync patterns that can be identified when searching a file.

See also:
next_sync(std::istream&)
Enumerator:
No_Sync_Type 
Line_Header_Sync_Type 
FELICS_Sync_Type 

Constructor & Destructor Documentation

Image_Line (  )

Constructs a default Image_Line.

The OFFSETS_TEMPLATE and ARRAY_COUNTS_TEMPLATE are used to define the component structure. The line header Sync element is initialized to the SYNC value; all other elements are initialized to 0.

References Image_Line::SYNC, and Image_Line::sync().

Image_Line ( unsigned int  bytes_per_pixel,
unsigned int  total_pixels,
unsigned int  total_lines = 0,
unsigned int  channel_number = CCD_UNKNOWN,
std::istream *  stream = NULL 
)

Constructs an Image_Line of a specified line length and pixel size.

The line header Sync element is initialized to the SYNC value; all other elements are initialized to 0.

Parameters:
bytes_per_pixelThe number of bytes per pixel.
total_pixelsThe total number of image pixels. This includes buffer and dark pixels (and any virtual pixels).
total_linesThe total number of image lines in the channel data set; includes both calibration and exposed image lines.
channel_numberThe expected channel number for the lines.
streamThe istream from which to obtain the line data.
Exceptions:
length_errorIf total_pixels is outside the allowable range of (BUFFER_PIXELS_COUNT + BLACK_PIXELS_COUNT) to MAX_PIXELS_PER_LINE.
out_of_rangeIf bytes_per_pixel is outside the allowable range of 1 to MAX_BYTES_PER_PIXEL.
See also:
pixel_count(unsigned int)
pixel_bytes(unsigned int)
Image_Line ( const Image_Line component,
bool  duplicate = true 
)

Copy constructor.

The new Image_Line has no data source.

Parameters:
componentThe Image_Line to be copied.
duplicatetrue if the data content of the copied component is to be duplicated in the copy; false if the data content is to be shared.
See also:
Data_Component(const Data_Component&, bool)
~Image_Line (  ) [virtual]

Destructor.

If the data block memory for the component has been substituted with a locally managed cache, the cache is deleted.

References Image_Line::Data_Cache.


Member Function Documentation

Image_Line & operator= ( const Image_Line component )

Assigns another Image_Line to this one.

The structure and data content of the source line are copied, but nothing else; the number of total_lines, expected channel number, and data source related information are unchanged.

Parameters:
componentThe Image_Line to be assigned.
See also:
Data_Component::operator=(const Data_Component&)

References Image_Line::Bytes_per_Pixel, Data_Component::operator=(), and Image_Line::Pixels_per_Line.

string id (  ) const [virtual]

Provides the class ID on a line followed by the base Data_Component::id.

Returns:
The multi-line identification string.
See also:
Data_Component::id()

Reimplemented from Data_Component.

References Image_Line::ID.

const char * name (  ) const [virtual]

Gets the NAME of this class.

Returns:
A pointer to the constant class name C-string.
See also:
Data_Component::name()

Implements Data_Component.

References Image_Line::NAME.

u_int_32 sync (  ) const

Gets the extended Sync Element value.

The Sync Element contains the 2 most significant bytes of a 32-bit value. The least significant byte has a value of 0. The remaining byte (1) is the upper SYNC_1_BIT_MASK bits of the Channel Element value with the remaining lower bits set to 0.

Returns:
A 32-bit extended Sync value.

References Image_Line::Channel, Image_Line::Sync, and Image_Line::SYNC_1_BIT_MASK.

Referenced by Image_Line::Image_Line(), Image_Line::is_valid(), Line_Cache::next_line(), and Image_Line::PVL().

Image_Line & sync ( u_int_32  value )

Sets the extended Sync Element value.

The 2 most significant bytes of the value put in the Sync Element. The next SYNC_1_BIT_MASK bits of the value are put in the Channel Element; the remainder of the Channel Element is left unchanged.

Parameters:
valueThe extended Sync Element value.
Returns:
This Image_Line.
u_int_32 channel (  ) const

Gets the Channel Element channel number.

Only the CHANNEL_BIT_MASK bits of the Channel Element value are used; the other bits are cleared in the return value.

Returns:
The channel number from the Channel Element.

References Image_Line::Channel, and Image_Line::CHANNEL_BIT_MASK.

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

Image_Line & channel ( u_int_32  channel_number )

Sets the Channel Element channel number.

Only the CHANNEL_BIT_MASK bits of the Channel Element value are changed; the other bits are unaffected.

Parameters:
channel_numberThe value to put in the Channel Element.
Returns:
This Image_Line.
u_int_32 expected_channel (  ) const [inline]

Gets the expected channel number for the line header.

For a valid line the expected channel number will match the channel number from the line header.

Returns:
The expected channel number.

References Image_Line::Channel_Number.

Referenced by Line_Cache::reset(), and Observation::reset_line().

Image_Line& expected_channel ( u_int_32  channel_number ) [inline]

Sets the expected channel number for the line header.

For a valid line the expected channel number will match the channel number from the line header.

Parameters:
channel_numberThe expected channel number.
Returns:
This Image_Line.
See also:
channel()

References Image_Line::Channel_Number.

u_int_32 line_number (  ) const

Gets the Line_Number Element value.

Returns:
The Line_Number Element value.

References Image_Line::Line_Number, and Image_Line::LINE_NUMBER_MASK.

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

Image_Line & line_number ( u_int_32  line )

Sets the Line_Number Element value.

Parameters:
lineThe line number to put in the Line_Number Element.
Returns:
This Image_Line.
bool bad_line (  ) const

Tests if the bad line flag is set.

Returns:
true if the flag is set; false otherwise.

References Image_Line::Line_Number, and Image_Line::LINE_NUMBER_MASK.

Referenced by main(), Line_Cache::next_line(), and Image_Line::PVL().

Image_Line & bad_line ( bool  state )

Sets or clears the bad line flag.

Parameters:
stateIf true, the flag is set; otherwise the flag is cleared.
Returns:
This Image_Line.
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.
See also:
bad_line()

Reimplemented in Line_Cache.

References Line_Cache::bad_line_description(), and Image_Line::Data_Cache.

Referenced by main().

Pixel_type pixel ( Index  index ) const

Gets a pixel value.

All pixel Elements are treated as a single line: Pixel 0 is the first of the Buffer_Pixels; pixel BUFFER_PIXELS_COUNT is the first of the Image_Pixels; pixel BUFFER_PIXELS_COUNT + count_of (Image_Pixels) is the first of the Black_Pixels.

Parameters:
indexThe Index of the pixel in the line.
Returns:
A generic Pixel_type value that is correct regardless of the number of pixel_bytes.
Exceptions:
out_of_rangeIf the index is greater than or equal to the pixel_count.

Referenced by main(), and Image_Line::PVL().

Pixel_type operator[] ( Index  index ) const

Gets a pixel value.

All pixel Elements are treated as a single line.

Warning: No range checking is applied.

Returns:
A generic Pixel_type value that is correct regardless of the number of pixel_bytes.
void pixel ( Index  index,
Pixel_type  value 
)

Sets a pixel value.

All pixel Elements are treated as a single line.

Parameters:
indexThe Index of the pixel in the line.
valueA generic Pixel_type value. The corrent number of pixel_bytes will be put in the data block.
Exceptions:
out_of_rangeIf the index is greater than or equal to the pixel_count.
invalid_argumentIf the value is greater than the MAX_PIXEL_VALUES for the number of pixel_bytes.
See also:
pixel(Index) const
Pixel_type buffer_pixel ( Index  index ) const

Gets a Buffer_Pixels Element value.

Parameters:
indexThe Index of the pixel in the Buffer_Pixels Element array portion of the line.
Returns:
A generic Pixel_type value that is correct regardless of the number of pixel_bytes.
Exceptions:
out_of_rangeIf the index is greater than or equal to the BUFFER_PIXELS_COUNT.
void buffer_pixel ( Index  index,
Pixel_type  value 
)

Sets a Buffer_Pixels Element value.

Parameters:
indexThe Index of the pixel in the Buffer_Pixels Element array portion of the line.
valueA generic Pixel_type value. The corrent number of pixel_bytes will be put in the data block.
Exceptions:
out_of_rangeIf the index is greater than or equal to the BUFFER_PIXELS_COUNT.
invalid_argumentIf the value is greater than the MAX_PIXEL_VALUES for the number of pixel_bytes.
Pixel_type image_pixel ( Index  index ) const

Gets an Image_Pixels Element value.

Parameters:
indexThe Index of the pixel in the Image_Pixels Element array portion of the line.
Returns:
A generic Pixel_type value that is correct regardless of the number of pixel_bytes.
Exceptions:
out_of_rangeIf the index is greater than or equal to the count_of (Image_Pixels).
void image_pixel ( Index  index,
Pixel_type  value 
)

Sets an Image_Pixels Element value.

Parameters:
indexThe Index of the pixel in the Image_Pixels Element array portion of the line.
valueA generic Pixel_type value. The corrent number of pixel_bytes will be put in the data block.
Exceptions:
out_of_rangeIf the index is greater than or equal to the count_of (Image_Pixels).
invalid_argumentIf the value is greater than the MAX_PIXEL_VALUES for the number of pixel_bytes.
Pixel_type black_pixel ( Index  index ) const

Gets a Black_Pixels Element value.

Parameters:
indexThe Index of the pixel in the Black_Pixels Element array portion of the line.
Returns:
A generic Pixel_type value that is correct regardless of the number of pixel_bytes.
Exceptions:
out_of_rangeIf the index is greater than or equal to the BLACK_PIXELS_COUNT.
void black_pixel ( Index  index,
Pixel_type  value 
)

Sets a Black_Pixels Element value.

Parameters:
indexThe Index of the pixel in the Black_Pixels Element array portion of the line.
valueA generic Pixel_type value. The corrent number of pixel_bytes will be put in the data block.
Exceptions:
out_of_rangeIf the index is greater than or equal to the BLACK_PIXELS_COUNT.
invalid_argumentIf the value is greater than the MAX_PIXEL_VALUES for the number of pixel_bytes.
Pixel_type virtual_pixel ( Index  index ) const

Gets a Virtual_Pixels Element value.

Parameters:
indexThe Index of the pixel in the Virtual_Pixels Element array portion of the line.
Returns:
A generic Pixel_type value that is correct regardless of the number of pixel_bytes.
Exceptions:
out_of_rangeIf the index is greater than or equal to the BUFFER_PIXELS_COUNT.
void virtual_pixel ( Index  index,
Pixel_type  value 
)

Sets a Virtual_Pixels Element value.

Parameters:
indexThe Index of the pixel in the Buffer_Pixels Element array portion of the line.
valueA generic Pixel_type value. The corrent number of pixel_bytes will be put in the data block.
Exceptions:
out_of_rangeIf the index is greater than or equal to the count_of (Virtual_Pixels).
invalid_argumentIf the value is greater than the MAX_PIXEL_VALUES for the number of pixel_bytes.
unsigned int pixel_count (  ) const [inline]

Gets the total number of pixels in the line.

This is the same as the total of count_of (Buffer_Pixels) (i.e. the constant BUFFER_PIXELS_COUNT), plus count_of (Image_Pixels), plus count_of (Black_Pixels) (i.e. the constant BLACK_PIXELS_COUNT), plus count_of (Virtual_Pixels) (typically 0, but the instrument manufacturer has been known to add these in some sample data sets).

Returns:
The line length.

References Image_Line::Pixels_per_Line.

Referenced by main(), Line_Cache::reset(), and Observation::reset_line().

Image_Line & pixel_count ( unsigned int  total_pixels )

Sets the total number of pixels in the line.

The structure of the component data block - both Element offsets and array counts - is adjusted accordingly.

The total number of pixels must include the BUFFER_PIXELS_COUNT and BLACK_PIXELS_COUNT. The remainder is allocated to the Image_Pixels Element. However, the number of Image_Pixels can not exceed the number of Instrument::CCD_IMAGES_SENSORS; any extra pixels are allocated as the Virtual_Pixels.

Parameters:
total_pixelsThe total number of pixels for the line.
Returns:
This Image_Line.
Exceptions:
length_errorIf total_pixels is outside the allowable range of (BUFFER_PIXELS_COUNT + BLACK_PIXELS_COUNT) to MAX_PIXELS_PER_LINE.

References ID.

unsigned int pixel_bytes (  ) const

Gets the number of bytes per pixel.

Returns:
The size of a pixel in bytes.

References Image_Line::Image_Pixels, and Data_Block::value_size_of().

Referenced by Observation::line(), main(), Line_Cache::reset(), and Observation::reset_line().

Image_Line & pixel_bytes ( unsigned int  bytes_per_pixel )

Sets the number of bytes per pixel.

The structure of the component data block - Element offsets - is adjusted accordingly.

Parameters:
bytes_per_pixelThe number of bytes per pixel.
Returns:
This Image_Line.
Exceptions:
out_of_rangeIf bytes_per_pixel is outside the allowable range of 1 to MAX_BYTES_PER_PIXEL.

References ID.

unsigned int total_lines (  ) const [inline]

Gets the total number of image lines in the channel data set.

This includes both calibration and exposed image lines.

Returns:
The number of lines to be expected.

References Image_Line::Total_Lines.

Referenced by main(), Observation::PVL_PDS(), Line_Cache::reset(), and Observation::reset_line().

Image_Line & total_lines ( unsigned int  lines )

Sets the total number of image lines in the channel data set.

This includes both calibration and exposed image lines.

N.B.: The count of the number of lines that have been read is reset to 0, as is the number of image data bytes that have been read.

Parameters:
linesThe maximum number of lines to be read.
Returns:
This Image_Line.
See also:
lines_read()
bytes_read()
read(std::istream&)
static unsigned int calibration_lines (  ) [inline, static]

Gets the number of image lines designated as calibration data.

Returns:
The number of calibration data lines.

References Image_Line::Calibration_Lines.

Referenced by main(), Image_Line::PVL_description(), Observation::PVL_PDS(), and Observation::reset_line().

void calibration_lines ( unsigned int  lines ) [static]

Sets the number of image lines designated as calibration data.

While the number of image lines designated as calibration data is really an observation characteristic (does not affect the structure of an Image_Line), it is used, along with the number of total lines, when generating line information for the PDS label.

N.B.: The effective number of calibration lines is not allowed to be greater than the total number of image lines; i.e. the specified number of calibration lines is the maximum number to be designated for the observation.

Parameters:
linesThe number of calibration lines.
See also:
Calibration_Lines
total_lines(unsigned int)
PVL_description()
void mirror (  )

Mirrors the order of all pixels.

Each of the HiRISE instrument 14 CCD assemblies is composed of two data channels - each getting its data from a CCD sensor device - aligned such that channel 0 is logically on the right, and channel 1 on the left, of a continuous linear pixel sensor array. Each CCD assembly has an electronics module (CPMM) that reads image data from the center of each CCD assembly. Thus channel 0 pixels are read out in reverse order from channel 1 resulting in channel 1 pixels having a logically mirrored view of the observation. However, the initial Buffer_Pixels are always read out first and the Black_Pixels are always read out last, so mirroring is applied to the image pixels segment independently. This method may be applied to reverse the ordering of image pixels to reflect the observation channel 1 pixels into the order consistent with the scene.

Warning: The pixel reordering is done independently of the Image_Line structure with the presumption that the structure is reversed and needs to be corrected. Thus this method should only be applied to an Image_Line by an application that knows, a priori, that the data order needs be corrected. If applied to correctly ordered data the resulting order will no longer be consistent with the actual image scene. Think at least twice before using this method!

N.B.: Only the image pixels are reordered. The other Image_Line segments remain as delivered by the instrument.

Note: The byte order of multibyte pixels is not changed. Each pixel retains its bytes in the same order, only the order of the pixels in the line is changed.

See also:
PIRL::reorder_bytes(unsigned char*, const unsigned long, const unsigned int)

References Image_Line::Buffer_Pixels, Image_Line::Bytes_per_Pixel, Data_Block::count_of(), Image_Line::Image_Pixels, Image_Line::LINE_HEADER_BYTES, reorder_bytes(), and Data_Block::size_of().

Referenced by Observation::line(), and main().

Image_Line & lookup ( const LUT lut )

Applies a LUT mapping to all pixel values.

Each pixel value is used as the index into the LUT to find a replacement single byte pixel value. The data value mapping is done in-place using the existing data block. N.B.: This method always reults in a one byte per pixel Image_Line.

If the number of pixel bytes is 1, then each pixel value is scaled up to 14-bits before being used as the index into the lut table for a replacement value. However, a pixel value of 0xFF is left unchanged which preserves gap data values.

For two byte pixels, any pixel value over the 14-bit limit results in an output pixel value of 0xFF; this has the effect of preserving gap data values and mapping out-of-range values to bad data values. The Image_Line is restructured as one byte per pixel.

Parameters:
lutThe LUT to be applied.
Returns:
This Image_Line.
See also:
pixel_bytes(unsigned int)
Image_Line & pukool ( Pixel_type *  table )

Applies a "reverse" table mapping to all pixel values.

The reverse mapping table is an array of 256 Pixel_type values. An input single byte pixel value is used as the index into the table to select the output value. Note: This mapping produces a multi-byte result from a single byte input.

The mapping is applied only if this Image_Line contains single byte pixels. The mapping is done in-place by utilizing the portion of the Data_Component MAX_COMPONENT_BYTES unoccupied by pixel data. The Image_Line is restructured to contain Pixel_type data.

Note: Entry 255 of the table is expected to contain the special value 65535 (0xFFFF) which ensures that gap pixel values retain gap pixel values.

Parameters:
tableAn array of 256 Pixel_type values.
Returns:
This Image_Line.

Referenced by main().

istream & source (  ) const

Gets the istream being used as the source of line data.

Returns:
An istream.
Exceptions:
invalid_argumentIf the Image_Line has no data source.
See also:
source(std::istream&)

Reimplemented in FELICS_Line_Cache, and Line_Cache.

References Image_Line::Data_Cache, Image_Line::ID, and Line_Cache::source().

Referenced by Observation::reset_line().

Image_Line & source ( std::istream &  stream )

Sets the input stream to be used as the source of line data.

N.B.: The line data cache is reset, which includes setting the count of the number of bytes_read to 0.

Parameters:
streamThe istream that will be used as the source of observation image data.
Returns:
This Image_Line.

Reimplemented in FELICS_Line_Cache, and Line_Cache.

bool next (  )

Gets the next image line.

The data cache is advanced to place the line data at the location of the next logical image line. If the next image line in the source stream is invalid - either because its line header does not indicate the correct next line number or because the following sync pattern is not at the correct location in the data stream - then a gap line containing the correct line header but with all pixels having gap data values is provided for the line data.

A count of the number of lines advanced since the source for this Image_Line was specified, or the total_lines count was last set, is maintained.

Returns:
true if the next line of image data was obtained; false otherwise.
Exceptions:
std::ios::failureIf the cache could not be refilled from the stream.
See also:
count()
total_lines(unsigned int)
source(std::istream&)
synchronization_lost()

References Image_Line::Data_Cache, and Line_Cache::next_line().

Referenced by Observation::line().

unsigned int count (  ) const

Gets the current line count.

The returned value 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).

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

Reimplemented in Line_Cache.

References Line_Cache::count(), and Image_Line::Data_Cache.

Referenced by Observation::line(), Observation::line_count(), and Image_Line::PVL().

unsigned long long bytes_read (  ) const

Gets the number of bytes read from the data source.

When the data source reset to a new stream, or the total number of lines to be expected is reset, the number of bytes read is reset to 0.

N.B.: The number of bytes read is not necessarily the total amount of line data provided. Only bytes read from the source stream are counted. Invalid lines replaced with gap data are not counted.

Returns:
The total number of image data bytes read from the source stream.
See also:
next()

Reimplemented in FELICS_Line_Cache, and Line_Cache.

References Line_Cache::bytes_read(), and Image_Line::Data_Cache.

Referenced by Observation::line(), and main().

unsigned long long source_bytes (  ) const

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.

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

Reimplemented in Line_Cache.

References Image_Line::Data_Cache, and Line_Cache::source_bytes().

Referenced by main().

bool compressed_data (  ) const

Indicates if the source line data was FELICS compressed.

Returns:
true if the image data source is FELICS compressed; false otherwise.

Reimplemented in FELICS_Line_Cache, and Line_Cache.

References Line_Cache::compressed_data(), and Image_Line::Data_Cache.

Referenced by main(), and Observation::PVL_PDS().

unsigned long long compressed_bytes (  ) const

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

Returns:
The number of bytes of compressed data that have been processed since the last cache reset.
See also:
reset()
source(std::istream&)

Reimplemented in FELICS_Line_Cache, and Line_Cache.

References Line_Cache::compressed_bytes(), and Image_Line::Data_Cache.

Referenced by main().

unsigned long long decompressed_bytes (  ) const

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

Returns:
The number of bytes of decompressed data that have been generated since the last cache reset.
See also:
reset()
source(std::istream&)

Reimplemented in FELICS_Line_Cache, and Line_Cache.

References Image_Line::Data_Cache, and Line_Cache::decompressed_bytes().

Referenced by main().

Line_Cache* cache (  ) [inline]

Gets the line's data management cache object.

>>> WARNING <<< The Line_Cache object is intended for use by the cache management system. It has direct control over the line's data contents using the istream source to supply data input.

Returns:
A pointer to the line's Line_Cache object. This will be NULL if the line is not attached to a source stream that would be used by the Line_Cache to provide structured line data input.

References Image_Line::Data_Cache.

Referenced by Line_Cache::next_line().

bool synchronization_lost (  )

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 position 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 in Line_Cache.

References Image_Line::Data_Cache, and Line_Cache::synchronization_lost().

Referenced by Observation::components().

ostream & print ( std::ostream &  stream = std::cout,
bool  verbose = false 
) const [virtual]

Prints the component structure and contents.

After listing the line header Elements each of the pixel Element portions is listed. The space separated pixel values are listed in width groups per line with the beginning of each line having the index number of the first Element pixel followed by a colon (':') character.

Parameters:
streamThe ostream where the listing will be written.
verbosetrue if the listing is to start with the class ID.
Returns:
The stream that was written.
See also:
Data_Component::print(std::ostream&, bool) const

Implements Data_Component.

References ID.

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

unsigned int width (  ) const [inline]

Gets the print listing width.

Returns:
The number of pixel groups per line.
See also:
print(std::ostream&, bool) const

References Image_Line::Width.

Image_Line& width ( unsigned int  groups ) [inline]

Sets the print listing width.

The DEFAULT_WIDTH applies if no other width has been set.

Parameters:
groupsThe number of pixel groups per line.
Returns:
This Image_Line.
See also:
print(std::ostream&, bool) const

References Image_Line::Width.

Aggregate * PVL (  ) const [virtual]
Aggregate * PVL_description (  ) const

Produces a PVL description of the observation image data layout for a PDS label.

The description is an OBJECT that contains the PDS parameters required to describe a data product binary data object. The Aggregate that is produced contains two sets of Parameter Objects: one for the initial calibration lines, where the object names all begin with "CALIBRATION_", and another for the exposed scene image lines. For each set a "LINE_PREFIX_TABLE" Object, "LINE_SUFFIX_TABLE" Object and "IMAGE" Object are provided. The returned Aggregate contains copies of static template Objects. In the copies the variable parameters that characterize the specific Image_Line structure are reset appropriately.

N.B.: The effective number of calibration lines will be set to the total number of lines if the specified number of calibration lines exceeds the total number of lines at the time that the PVL is generated. The specified number of calibration lines will remain unchanged in any case.

Returns:
A pointer to a PVL::Aggregate.

References Image_Line::Black_Pixels, Image_Line::BLACK_PIXELS_COUNT, Image_Line::Buffer_Pixels, Image_Line::Bytes_per_Pixel, Image_Line::Calibration_Lines, Image_Line::calibration_lines(), Parameter::comment(), Aggregate::copy_in(), Data_Block::count_of(), Parser::get_parameters(), Image_Line::ID, Image_Line::Image_Pixels, Image_Line::LINE_HEADER_BYTES, Parameter::name(), Data_Block::offset_of(), Data_Block::size_of(), Image_Line::Total_Lines, Parameter::value(), and Image_Line::Virtual_Pixels.

Referenced by Observation::PVL_PDS().

bool is_valid (  ) const [virtual]

Tests if the component data is valid.

The sync value must match the SYNC constant, and the number of lines_read must be one more that the line_number.

Returns:
true if the component has valid data; false otherwise.

Implements Data_Component.

References Image_Line::SYNC, and Image_Line::sync().

bool is_sync ( void *  data_at ) [static]

Tests if some data contains a line header sync pattern.

The data must contain at least 3, MSB ordered, bytes having a Image_Line::SYNC value for the test to be true.

Parameters:
data_atA pointer to the data to be tested.
Returns:
true if the data contains a SYNC value; false otherwise.

Reimplemented in FELICS_Line_Cache.

Referenced by Image_Line::next_sync().

Image_Line::Sync_Type next_sync ( std::istream &  stream ) [static]

Searches an istream for an image data synchronization pattern.

The data from the stream is incrementally searched for the presence of either a line header sync pattern or a FELICS data block sync pattern. The first occurance of either determines the Sync_Type returned. If neither can be found in the entire file a value of No_Sync_Type is returned.

>>> WARNING <<< The input stream must be seekable. The file is repositioned back to its position at the start of the search before the function returns.

Parameters:
streamThe istream to be searched.
Returns:
A Sync_Type value.
See also:
is_sync(void*)
FELICS_Line_Cache::is_sync(void*)

References ID, FELICS_Line_Cache::is_sync(), Image_Line::is_sync(), FELICS_Line_Cache::SYNC_BYTES, and SYNC_SEARCH_BUFFER_SIZE.


Member Data Documentation

const char *const ID = "UA::HiRISE::Image_Line (1.42 2010/11/25 02:51:13)" [static]

Class identification name with source code version and date.

Reimplemented from Data_Component.

Reimplemented in FELICS_Line_Cache, and Line_Cache.

Referenced by Image_Line::id(), main(), Image_Line::PVL_description(), and Image_Line::source().

const char *const NAME = "Image Line" [static]

The component name.

Referenced by Image_Line::name(), and Image_Line::PVL().

const char * NAMES [static]
Initial value:
        {
        "SYNC",
        "CHANNEL",
        "LINE_NUMBER",
        "BUFFER_PIXELS",
        "IMAGE_PIXELS",
        "BLACK_PIXELS",
        "VIRTUAL_PIXELS",
        NULL
        }

The name of each Element.

Referenced by Image_Line::PVL().

const unsigned int LINE_HEADER_BYTES = 6 [static]

The number of bytes in the line header section.

Referenced by Observation::line(), Image_Line::mirror(), and Image_Line::PVL_description().

const unsigned int BUFFER_PIXELS_COUNT = 12 [static]

The number of buffer pixels.

Referenced by set_effective_values().

const unsigned int BLACK_PIXELS_COUNT = 16 [static]

The number of black pixels.

Referenced by Image_Line::PVL_description(), and set_effective_values().

const unsigned int MAX_VIRTUAL_PIXELS_COUNT = MAX_VIRTUAL_PIXELS [static]

The maximum number of allowable virtual pixels.

const unsigned int MAX_PIXELS_PER_LINE [static]
const unsigned int DEFAULT_CALIBRATION_LINES = CALIBRATION_LINES [static]

The default number of calibration lines at the beginning of the observation channel data.

The pixel data in these lines are not a result of being exposed to the viewing optics, or are for other reasons not to be included in the scene image data lines. These lines are used to calibrate the following image data lines for the effects of instrument electronics.

Referenced by main(), Observation::reset_line(), and usage().

const Index MAX_COMPONENT_BYTES [static]
Initial value:

Total maximum number of bytes in the Data_Block.

const Index OFFSETS_TEMPLATE [static]
Initial value:

Data_Block data storage address offset template for each Element.

The template is used to construct a default Image_Line with MAX_BYTES_PER_PIXEL, Instrument::CCD_IMAGE_SENSORS image pixels, and no virtual pixels.

const Index ARRAY_COUNTS_TEMPLATE [static]
Initial value:

Data_Block array element value counts each keyed to an Element Index.

All values of an array element are the same size (the total size of the Element divided by the count of array entries). Any Element not listed here has only one value.

The template is used to construct a default Image_Line with Instrument::CCD_IMAGE_SENSORS image pixels, and no virtual pixels.

ARRAY_COUNTS[*][0]
An Element Index.
ARRAY_COUNTS[*][1]
The number of array values for the indexed Element.

This list must be zero-terminated.

See also:
Data_Block::size_of(Index)
Data_Block::count_of(Index)
const u_int_32 SYNC = 0xFF00E000 [static]

Expected Sync Element value after extension.

The Sync Element contains the most significant bytes of a 32-bit value. The least significant byte has a value of 0. The remaining byte (1) is the Channel Element value with the CHANNEL_BIT_MASK lower bits set to 0 (only the upper SYNC_1_BIT_MASK bits are used).

Referenced by Image_Line::Image_Line(), Image_Line::is_valid(), Line_Cache::next_line(), and Image_Line::PVL().

const u_int_8 SYNC_3 = 0xFF [static]

Expected Sync Element MSB (byte 3) value.

See also:
SYNC
const u_int_8 SYNC_2 = 0x00 [static]

Expected Sync Element MSB+1 (byte 2) value.

See also:
SYNC
const u_int_8 SYNC_1_BIT_MASK = 0xE0 [static]

Bit mask for the Sync Element extension field of the Channel Element.

See also:
SYNC

Referenced by Image_Line::sync().

const u_int_8 CHANNEL_BIT_MASK = 0x1F [static]

Bit mask for channel number field of the Channel Element.

Referenced by Image_Line::channel().

const u_int_32 LINE_NUMBER_MASK = 0x007FFFFF [static]

Bit mask for the line number field of the Line_Number Element.

For EDR products the most significant bit of the Line_Number Element is reserved as a bad line flag. The bad line flag will only be set when the source observation image data was found to have a damaged structure for the line.

Referenced by Image_Line::bad_line(), and Image_Line::line_number().

const char * Sync_Type_Names [static]
Initial value:
        {
        "None",
        "Line header",
        "FELICS"
        }

Sync_Type names.

const unsigned int DEFAULT_WIDTH = LINE_PRINT_GROUPS_WIDTH [static]

The default width, in pixel groups, of a print listing.

unsigned int Calibration_Lines = CALIBRATION_LINES [static]

Number of image lines at the beginning of the image data to be designated as calibration data.

Default number of calibration lines.

The pixel data in these lines are not a result of being exposed to the viewing optics, or are for other reasons not to be included in the scene image data lines. These lines are expected to be used to calibrate the following image data lines for the effects of instrument electronics.

Referenced by Image_Line::calibration_lines(), and Image_Line::PVL_description().

unsigned int Pixels_per_Line [protected]

Total pixels in a line.

Referenced by Image_Line::operator=(), and Image_Line::pixel_count().

unsigned int Bytes_per_Pixel [protected]
unsigned int Total_Lines [protected]

Total number of lines expected.

Referenced by Line_Cache::next_line(), Image_Line::PVL_description(), and Image_Line::total_lines().

unsigned int Channel_Number [protected]

Expected channel number.

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

Line_Cache* Data_Cache [protected]
unsigned int Width [protected]

Width of listing (pixel groups).

Referenced by Image_Line::width().


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