GrabbaMRTD_Image Class Reference

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 the DataEvent in GrabbaMRTD_Listener to receive images from MRTDs.

Note

All property values are passed by copy; a new copy of the value will be generated each time a property is read.

Thread safety:

• Concurrent accesses to distinct objects: safe
• Concurrent accesses to the same object: unsafe, unless all accesses are read-only (i.e. property reads)

Inheritance diagram for GrabbaMRTD_Image:

Instance Methods
(NSData *_Nonnull)	- decodeJPEG2000
	Decode the JPEG 2000 content, if any, to the Microsoft BMP (DIB) format. More...
(NSString *_Nonnull)	- encodeAsBase64
	Generate a MIME-compliant Base64 encoding of the image data. More...
(instancetype _Nullable)	- init
	Initialise a null (empty) image object. More...
(instancetype _Nullable)	- initFromData:offset:
	Initialise an image object by extracting data from a raw byte array. More...
(instancetype _Nullable)	- initFromStructure:
	Initialise an image object by extracting data from a BER-TLV structure. More...

Class Methods
(instancetype _Nullable)	+ image
	Allocate and initialise a null (empty) image object. More...
(instancetype _Nullable)	+ imageWithData:offset:
	Initialise an image object by extracting data from a raw byte array. More...
(instancetype _Nullable)	+ imageWithStructure:
	Allocate and initialise an image object by extracting data from a BER-TLV structure. More...

Properties
NSData *_Nonnull	data
	Copy the image data as a raw byte array. More...
BOOL	JPEG2000
	Was a JPEG 2000 data block successfully extracted at init? More...
BOOL	valid
	Was a data block successfully extracted at init? More...

Method Documentation

decodeJPEG2000()

- (NSData* _Nonnull) 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 array

encodeAsBase64()

- (NSString* _Nonnull) 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

image()

+ (instancetype _Nullable) image

Allocate and initialise a null (empty) image object.

Returns

Pointer to initialised object if initialisation succeeded; nil if it failed

imageWithData:offset:()

+ (instancetype _Nullable) imageWithData:		(NSData *_Nonnull)	data
offset:		(size_t)	offset

Initialise an image object by extracting data from a raw byte array.

This method scans the supplied data for a JPEG or JPEG2000 preamble. The first such data block will be stored inside the newly-initialised object; if no such block is found, then the object will hold no data.

Parameters

data	Collection of data from which the image is to be read
offset	Offset within the supplied data at which scanning should commence; typically set to zero

Returns

Pointer to initialised object if initialisation succeeded; nil if it failed

imageWithStructure:()

+ (instancetype _Nullable) imageWithStructure:

(GrabbaBER_TLV *_Nonnull)

structure

Allocate and initialise an image object by extracting data from a BER-TLV structure.

This method 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 newly-initialised 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

structure

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

Returns

Pointer to initialised object if initialisation succeeded; nil if it failed

init()

- (instancetype _Nullable) init

Initialise a null (empty) image object.

Returns

Pointer to initialised object if initialisation succeeded; nil if it failed

initFromData:offset:()

- (instancetype _Nullable) initFromData:		(NSData *_Nonnull)	data
offset:		(size_t)	offset

Initialise an image object by extracting data from a raw byte array.

This method scans the supplied data for a JPEG or JPEG2000 preamble. The first such data block will be stored inside the newly-initialised object; if no such block is found, then the object will hold no data.

Parameters

data	Collection of data from which the image is to be read
offset	Offset within the supplied data at which scanning should commence; typically set to zero

Returns

Pointer to initialised object if initialisation succeeded; nil if it failed

initFromStructure:()

- (instancetype _Nullable) initFromStructure:

(GrabbaBER_TLV *_Nonnull)

structure

Initialise an image object by extracting data from a BER-TLV structure.

This method 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 newly-initialised 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

structure

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

Returns

Pointer to initialised object if initialisation succeeded; nil if it failed

Property Documentation

data

- (NSData* _Nonnull) data

readnonatomiccopy

Copy the image data as a raw byte array.

Note

If extraction was unsuccessful, this property will contain an empty NSData object.

JPEG2000

- (BOOL) JPEG2000

readnonatomicassign

Was a JPEG 2000 data block successfully extracted at init?

valid

- (BOOL) valid

readnonatomicassign

Was a data block successfully extracted at init?

YES if either a JPEG or JPEG 2000 block was extracted; NO otherwise