Description

Provides extraction and conversion capabilities for images embedded in Machine-Readable Travel Documents (MRTDs)

This class provides convenience functions for extracting and converting MRTD image data to suitable formats for display or processing. It may be used in conjunction with MRTD_Listener.readCompleteEvent to retrieve images from MRTDs.

Thread safety:

The current version of this class is immutable, and thus thread-safe
Future updates to this class may guarantee thread-safety only to the following level:
- Concurrent accesses to distinct objects: safe
- Concurrent accesses to the same object: unsafe, unless all accesses are read-only (query functions, decodeJPEG2000(), encodeAsBase64())

Public Member Functions
	MRTD_Image ()
	Default constructor - empty (null) image.

	MRTD_Image (@NonNull BER_TLV data)
	Constructor - extracts MRTD image data from a BER-TLV structure. More...

	MRTD_Image (@NonNull byte[] data, long offset)
	Constructor - extracts MRTD image data from a byte array. More...

byte []	data ()
	Image data, passed by copy More...

byte []	decodeJPEG2000 ()
	Decode the JPEG 2000 content, if any, to the Microsoft BMP (DIB) format. More...

String	encodeAsBase64 ()
	Generate a MIME-compliant Base64 encoding of the image data. More...

boolean	JPEG2000 ()
	Was a JPEG 2000 data block successfully extracted at construction? More...

boolean	valid ()
	Was a data block successfully extracted at construction? More...

Constructor & Destructor Documentation

◆ MRTD_Image() [1/2]

MRTD_Image ( @NonNull BER_TLV data )

Constructor - extracts MRTD image data from a BER-TLV structure.

The constructor scans the supplied BER-TLV object for a primitive data field with tag #46, and containing JPEG or JPEG2000 preambles. The first such data block will be stored inside the constructed object; if no such block is found, then the object will hold no data.

Note that the contents of the data will not be validated beyond checking whether the preambles are present.

Parameters

data	BER-TLV data read from an MRTD, typically taken from a MRTD_Listener callback

◆ MRTD_Image() [2/2]

MRTD_Image	(	@NonNull byte []	data,
		long	offset
	)

Constructor - extracts MRTD image data from a byte array.

The constructor scans the supplied data for a JPEG or JPEG2000 preamble, providing a valid offset is supplied. The first such data block will be stored inside the constructed object; if no such block is found, or if the supplied offset is out of range for the supplied data, then the constructed object will hold no data.

Parameters

data	Collection of data from which the image is to be read
offset	If non-zero, scanning for data block commences at the specified offset rather than the beginning of the array; typically set to zero. Valid range 0 to data.length-1 (inclusive).

Member Function Documentation

◆ data()

byte [] data ( )

Image data, passed by copy

Returns: Raw image data if data extraction (at construction) succeeded, otherwise an empty byte array

◆ decodeJPEG2000()

byte [] decodeJPEG2000 ( )

Decode the JPEG 2000 content, if any, to the Microsoft BMP (DIB) format.

Returns: BMP version of image if image data block is in JPEG 2000 format, otherwise an empty byte array

◆ encodeAsBase64()

String encodeAsBase64 ( )

Generate a MIME-compliant Base64 encoding of the image data.

If the supplied data is in JPEG (JFIF) format, then it will be encoded in Base64 without any prior conversion. If the supplied image is in JPEG 2000 format, then it will be converted to BMP (DIB) format prior to Base64 encoding. If the supplied data is invalid, or in any other format, then an empty string will be returned.

Returns: Generated MIME/Base64 encoding if the encoding succeeded, otherwise an empty string

◆ JPEG2000()

boolean JPEG2000 ( )

Was a JPEG 2000 data block successfully extracted at construction?

Returns: True if a JPEG 2000 data block was extracted; false if extraction failed or a JPEG (JFIF) data block was extracted

◆ valid()

boolean valid ( )

Was a data block successfully extracted at construction?

Returns: True if extraction succeeded; false if it failed