Atalasoft MobileImage API Reference
Classes | Public Member Functions | Static Public Attributes | List of all members
Image Class Reference

The Image Object contains an in-memory and/or image file based representation of an image. This object is serializable. More...

Inheritance diagram for Image:

Classes

enum  FileIOEngine
 An enum which optionally identifies the desired File I/O Engine used for reading and writing. More...
 
enum  FileRestriction
 An enum which specifies that ANSI X9.100-181 restrictions are needed for TIFF output. More...
 
enum  ImageFileRep
 An enum which identifies the File Representation of the image file referenced by this Image Object. More...
 
enum  ImageMimeType
 An enum which identifies the Mime Type of the image file referenced by this Image Object. More...
 
enum  ImageRep
 An enum which identifies the Image Representation(s) included in this Image Object. More...
 
enum  OutputColor
 An enum which identifies the output color desired for writing the bitmap to an image file. More...
 

Public Member Functions

long getImageSize ()
 Returns the size of the image. When the representation is both returns the size of the file. More...
 
 Image ()
 The default Constructor creates an empty Image object. More...
 
 Image (Bitmap bitmap) throws NullPointerException
 This Constructor creates an Image object initialized with the Bitmap passed in. More...
 
 Image (File file, ImageMimeType imgMimeType)
 This Constructor creates an Image object initialized with the image File passed in. More...
 
 Image (String imgFilePath, ImageMimeType imgMimeType)
 This Constructor creates an Image object initialized with the image file path passed in. More...
 
String getImageFilePath ()
 Get the path to an image file which is represented by this Image object. More...
 
void setImageFilePath (String imgFilePath) throws KmcRuntimeException
 Set the path to an image file which this Image object will represent. More...
 
ImageMimeType getImageMimeType ()
 Get the MIME type of this Image object, if an image file representation exists. More...
 
void setImageMimeType (ImageMimeType imgMimeType)
 Set the MIME type of this Image object, if an image file representation exists. More...
 
Bitmap getImageBitmap ()
 Get the Bitmap representation of the Image object. More...
 
void setImageBitmap (Bitmap imgBitmap) throws KmcRuntimeException
 Set the Bitmap representation of this Image object. More...
 
ImageRep getImageRepresentation ()
 Gets the ways in which the image data is represented in this Image object. More...
 
Integer getImageBitmapWidth ()
 Gets the image width in pixels of the Bitmap representation of this Image object. More...
 
Integer getImageBitmapHeight ()
 Gets the image height in pixels of the Bitmap representation of this Image object. More...
 
Float getImageBitmapScaling ()
 Gets the scaling factor used to scale the bitmap when reading in from an image file. More...
 
Integer getImageFileWidth ()
 Gets the image width in pixels of the File representation of this Image object. More...
 
Integer getImageFileHeight ()
 Gets the image height in pixels of the File representation of this Image object. More...
 
String getImageTag ()
 Gets the application-defined tag for this Image object. More...
 
void setImageTag (String imgTag)
 Sets the application-defined tag for this Image object. More...
 
String getImageID ()
 Gets an ID which uniquely identifies this Image. More...
 
String getImageSrcID ()
 Gets the imageID if the original input image. More...
 
String getImageMetaData ()
 Gets the full image metadata generated by the ImageProcessor Engine. More...
 
ImagePerfectionProfile getImagePerfectProfileUsed ()
 Gets the Image Perfection Profile used to generate this Image object. More...
 
BasicSettingsProfile getBasicSettingsProfileUsed ()
 Gets the Basic Settings Profile used to generate this Image object. More...
 
QuickAnalysisFeedback getImageQuickAnalysisFeedBack ()
 Gets the results from calling the doQuickAnalysis method on the ImageProcessor object. More...
 
Float getImageLatitude ()
 Gets the GPS latitude associated with the image at the time it was generated. More...
 
Float getImageLongitude ()
 Gets the GPS longitude associated with the image at the time it was generated. More...
 
List< BarCodeResultgetImageBarCodes ()
 Gets an array of BarCodeResult objects representing bar codes found on this image. More...
 
void setImageBarCodes (List< BarCodeResult > imageBarCodes)
 Sets an array of BarCodeResult objects representing bar codes found on this image. More...
 
List< ImageClassificationResultgetImageClassifyResults ()
 Gets an array of ImageClassificationResult objects representing the result of classifying this image. More...
 
void setImageClassifyResults (List< ImageClassificationResult > imgClassifyResults)
 Sets an array of ImageClassificationResult objects representing the result of classifying this image. More...
 
Float getImagePitch ()
 Gets the pitch of the camera in degrees when the image was taken. More...
 
Float getImageRoll ()
 Gets the roll of the camera in degrees when the image was taken. More...
 
String getImageCreateDateTime ()
 Gets the date and time the image was created, in ISO 8601 format. More...
 
void setImageCreateDateTime (String imgCreateDateTime)
 Sets the date and time the image was created, in ISO 8601 format. More...
 
Integer getImageDPI ()
 Get the resolution of this image in Dots Per Inch. More...
 
void setImageDPI (int imgDPI)
 Set the resolution of this image in Dots Per Inch. More...
 
Integer getImageJpegQuality ()
 Get the JPEG image quality for JPEG image files. More...
 
void setImageJpegQuality (int imgJpegQuality)
 Set the JPEG image quality for JPEG image files. More...
 
OutputColor getImageOutputColor ()
 Get the bits per pixel of the image file representation of this Image object. More...
 
void setImageOutputColor (OutputColor imgOutputColor)
 Set the bits per pixel of the image file representation of this Image object. More...
 
ImageFileRep getImageFileRep ()
 Gets the way in which the file is stored for this Image object. More...
 
ByteBuffer getImageFileBuffer ()
 Gets the in-memory ByteBuffer created by a previous call to imageWriteToFileBuffer. More...
 
ErrorInfo imageWriteToFile () throws KmcException, KmcRuntimeException
 Writes the bitmap in the imageBitmap property to the file specified in ImageFilePath property. More...
 
ErrorInfo imageWriteToFile (FileIOEngine engine) throws KmcException, KmcRuntimeException
 Writes the bitmap in the imageBitmap property to the file specified in ImageFilePath property. More...
 
ErrorInfo imageWriteToFile (FileRestriction fileRestriction) throws KmcException, KmcRuntimeException
 Writes the bitmap in the imageBitmap property to the file specified in ImageFilePath property. More...
 
ErrorInfo imageWriteToFileBuffer () throws KmcException, KmcRuntimeException
 Writes the bitmap in the imageBitmap property to the internal imageFileBuffer. More...
 
ErrorInfo imageWriteToFileBuffer (FileIOEngine engine) throws KmcException, KmcRuntimeException
 Writes the bitmap in the imageBitmap property to the internal imageFileBuffer. More...
 
ErrorInfo imageWriteToFileBuffer (FileRestriction fileRestriction) throws KmcException, KmcRuntimeException
 Writes the bitmap in the imageBitmap property to the internal imageFileBuffer. More...
 
ErrorInfo imageReadFromFile () throws KmcException, KmcRuntimeException
 Reads a bitmap in from an image file of MimeType specified in this object. More...
 
ErrorInfo imageReadFromFile (float imgBitmapScaling) throws KmcException, KmcRuntimeException
 Reads a bitmap in from an image file using the specified scaling factor. More...
 
ErrorInfo imageReadFromFileBuffer () throws KmcException, KmcRuntimeException
 Creates a bitmap from the image file buffer contained in this Image. More...
 
ErrorInfo imageReadFromFileBuffer (float imgBitmapScaling) throws KmcException, KmcRuntimeException
 Creates a bitmap from the image file buffer contained in this Image. More...
 
ErrorInfo imageDeleteFile () throws KmcException, KmcRuntimeException
 Deletes the image file in the native storage, and sets the FilePath property to null. More...
 
ErrorInfo imageClearBitmap ()
 If a Bitmap representation exists, the bitmap is cleared, and the imageRepresentation property is updated accordingly. More...
 
ErrorInfo imageClearFileBuffer () throws KmcException
 If a file buffer representation exists, the buffer is cleared, and the imageRepresentation property is updated accordingly. More...
 
Bitmap createScaledBitmap (float imgBitmapScaling) throws KmcException
 If a Bitmap representation exists, a scaled copy of the bitmap is returned, using the specified scaling factor. More...
 
String getMicrData () throws JSONException
 
void setMicrData (String micrData) throws NullPointerException
 
Rect getTargetFrame ()
 
void setTargetFrame (Rect targetFrame)
 

Static Public Attributes

static final int MIN_JPEG_QUALITY = 1
 
static final int MAX_JPEG_QUALITY = 100
 
static final int DEFAULT_JPEG_QUALITY = 90
 
static final float MIN_SCALING_FACTOR = 0.1f
 
static final float MAX_SCALING_FACTOR = 1.0f
 

Detailed Description

The Image Object contains an in-memory and/or image file based representation of an image. This object is serializable.

The Image object can also contain certain results of operations performed on the Image object by Engine or UiControl objects. An object of this class can be instantiated in three ways:

Important: In general, mobile devices have significant memory constraints, and require careful memory management. This is particularly true with regard to images. Bitmaps, especially those taken with higher pixel-count cameras, consume large blocks of memory. When finished with an Image object, the calling application must be sure to call the imageClearBitmap() and imageClearFileBuffer() methods on the Image to avoid out-of-memory problems.

The application should never call recycle on any app reference to the internal Android Bitmap object contained within the Image object. The call to imageClearBitmap() will recycle the internal Bitmap. All application references to the internal Android Bitmap object should be set to null prior to calling the imageClearBitmap(). Not doing so may prevent garbage collection from running, thus preventing the reclaiming of memory consumed by the internal Android Bitmap.

Example of how to use and dispose of the Bitmap contained within an Image object:

Bitmap bitmap = getMyDisplayBitmap();
Image image = new Image(bitmap);
// Done with this local Bitmap reference
bitmap = null;
// Get the internal Android Bitmap object
Bitmap myDisplayBitmap = image.getImageBitmap();
// Do something useful with it
showMyBitmapInUI(myDisplayBitmap);
// Ensure I don't keep a reference to the internal Bitmap
myDisplayBitmap = null;
// Must be called else it will result in a memory leak
image.imageClearBitmap()

The following sample serializes the Image object:

File dest = new File(Environment.getExternalStorageDirectory() + File.separator + "IMAGE_REP_FILE_STORED.save");
FileOutputStream fos = null;
ObjectOutputStream out = null;
try {
String imageFilePath = "STORAGE_PATH" + File.separator + "Example.jpg";
Image myImage = new Image(imageFilePath, Image.ImageMimeType.MIMETYPE_JPEG);
fos = new FileOutputStream(dest);
out = new ObjectOutputStream(fos);
out.writeObject(myImage);
} catch (KmcRuntimeException e) {
e.printStackTrace();
} catch (Exception ex) {
ex.printStackTrace();
} finally {
// Close streams
}

The following sample deserializes the Image object:

File src = new File(Environment.getExternalStorageDirectory() + File.separator + "IMAGE_REP_FILE_STORED.save");
FileInputStream fis = null;
ObjectInputStream in = null;
try {
fis = new FileInputStream(src);
in = new ObjectInputStream(fis);
Image myImageCopy = (Image)in.readObject();
} catch (KmcRuntimeException e) {
e.printStackTrace();
} catch (Exception ex) {
ex.printStackTrace();
} finally {
// Close streams
}

Constructor & Destructor Documentation

Image ( )

The default Constructor creates an empty Image object.

Image ( Bitmap  bitmap) throws NullPointerException

This Constructor creates an Image object initialized with the Bitmap passed in.

Parameters
bitmapMust be set to a valid Android Bitmap object.
Exceptions
NullPointerException(bitmap parameter is null).
Image ( File  file,
ImageMimeType  imgMimeType 
)

This Constructor creates an Image object initialized with the image File passed in.

This image file must be one of the MimeTypes included in the ImageMimeType enumeration. Only image files that are stored locally on the file system of the mobile device are supported. Image file paths which include a web address are not supported.

Parameters
fileA File object representing an image file in the local file system of the mobile device.
imgMimeTypeThe ImageMimeType of the image file represented by the 'file' parameter.
Exceptions
NullPointerException(file parameter is null).
IllegalArgumentException(imgMimeType cannot be set to UNKNOWN).
IllegalArgumentException(file does not exist).
IllegalArgumentException(imgMimeType does not match MIME type of file).
Image ( String  imgFilePath,
ImageMimeType  imgMimeType 
)

This Constructor creates an Image object initialized with the image file path passed in.

This image file must be one of the MimeTypes included in the ImageMimeType enumeration. Only image files that are stored locally on the file system of the mobile device are supported. Image file paths which include a web address are not supported.

Parameters
imgFilePathA file path representing an image file in the local file system of the mobile device.
imgMimeTypeThe ImageMimeType of the image file represented by the 'imgFilePath' parameter.
Exceptions
NullPointerException(imgFilePath parameter is null).
IllegalArgumentException(imgMimeType cannot be set to UNKNOWN).
IllegalArgumentException(imgFilePath does not exist).
IllegalArgumentException(imgMimeType does not match MIME type of imgFilePath).

Member Function Documentation

Bitmap createScaledBitmap ( float  imgBitmapScaling) throws KmcException

If a Bitmap representation exists, a scaled copy of the bitmap is returned, using the specified scaling factor.

This method will create a scaled copy of the Bitmap representation of this object. The imgBitmapScaling parameter must be greater than 0.1 and less than or equal to 1.0. For example, to scale the image by half, specify a value of 0.5. for no scaling, specify a value of 1.0.

The original bitmap stored internally as the Bitmap representation of this object is not modified (remains its original size).

Parameters
imgBitmapScalingSpecifies the factor used to scale the bitmap.
Returns
Bitmap A scaled copy of the internal Bitmap representation of this object.
Exceptions
KmcRuntimeException(KMC_ED_OBJECT_REP_NO_BITMAP).
KmcException(KMC_GN_OUT_OF_MEMORY).
KmcRuntimeException(KMC_ED_IMAGE_INVALID_SCALING_FACTOR).
BasicSettingsProfile getBasicSettingsProfileUsed ( )

Gets the Basic Settings Profile used to generate this Image object.

This property will be filled in by the ImageProcessor Engine when returning a processed Image object.

List<BarCodeResult> getImageBarCodes ( )

Gets an array of BarCodeResult objects representing bar codes found on this image.

This property will be filled in by the BarCodeReader Engine when returning a processed Image object.

Bitmap getImageBitmap ( )

Get the Bitmap representation of the Image object.

Integer getImageBitmapHeight ( )

Gets the image height in pixels of the Bitmap representation of this Image object.

If there is no Bitmap representation, null is returned indicating bitmap image height is uninitialized.

Float getImageBitmapScaling ( )

Gets the scaling factor used to scale the bitmap when reading in from an image file.

This value is set when imageReadFromFile, imageReadFromFileBuffer, and createScaledBitmap methods are called that take a bitmap scaling parameter.

The bitmap scaling factor must be greater than 0.1 and less than 1. For example, to scale the image by half, set a value of 0.5 as the ImageBitmapScaling property. By default, the ImageBitmapScaling is set to 1, which means no scaling is performed.

See also
imageReadFromFile(float imgBitmapScaling)
imageReadFromFileBuffer(float imgBitmapScaling)
createScaledBitmap(float imgBitmapScaling)
Integer getImageBitmapWidth ( )

Gets the image width in pixels of the Bitmap representation of this Image object.

If there is no Bitmap representation, null is returned indicating bitmap image width is uninitialized.

List<ImageClassificationResult> getImageClassifyResults ( )

Gets an array of ImageClassificationResult objects representing the result of classifying this image.

This property will be filled in by the Classifier Engine when returning a classified Image object.

String getImageCreateDateTime ( )

Gets the date and time the image was created, in ISO 8601 format.

Example of how to convert ISO 8601 formatted string to Java Date object:

SimpleDateFormat simpleDF = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZZZZZ");
Date date = simpleDF.parse(imgCreateDateTime);
Integer getImageDPI ( )

Get the resolution of this image in Dots Per Inch.

The ImageDPI property will be set by the Image Processor Engine, to represent the output DPI of a processed image. The DPI may also be set on a call to imageReadFromFile() method, if it can be determined based on the image file header. If the DPI is not known or never set, the getImageDPI() method will return null.

If the imageWriteToFile() is called, a default value of 72 DPI will be used when writing an in-memory bitmap to an image file, if none is specified.

ByteBuffer getImageFileBuffer ( )

Gets the in-memory ByteBuffer created by a previous call to imageWriteToFileBuffer.

Returns a ByteBuffer containing the compressed image file buffer bytes that were created by a previous call to imageWriteToFileBuffer.

Example of how to allocate a new byte array and fill it with the image file compressed data codes:

ByteBuffer bb = image.getImageFileBuffer();
byte[] ba = new byte[bb.capacity()];
bb.get(ba);
Integer getImageFileHeight ( )

Gets the image height in pixels of the File representation of this Image object.

If there is no File representation, null is returned indicating file image height is uninitialized.

String getImageFilePath ( )

Get the path to an image file which is represented by this Image object.

ImageFileRep getImageFileRep ( )

Gets the way in which the file is stored for this Image object.

An image in this Image object can be stored as a file on the device or an in-memory buffer.

Integer getImageFileWidth ( )

Gets the image width in pixels of the File representation of this Image object.

If there is no File representation, null is returned indicating file image width is uninitialized.

String getImageID ( )

Gets an ID which uniquely identifies this Image.

The application can get an ID which uniquely identifies this Image.

Integer getImageJpegQuality ( )

Get the JPEG image quality for JPEG image files.

Float getImageLatitude ( )

Gets the GPS latitude associated with the image at the time it was generated.

This property is typically set by the image capture control. This property will be filled in by the ImageProcessor Engine to the imageLatitude of the input Image when returning a processed Image object

Float getImageLongitude ( )

Gets the GPS longitude associated with the image at the time it was generated.

This property is typically set by the image capture control. This property will be filled in by the ImageProcessor Engine to the imageLongitude of the input Image when returning a processed Image object

String getImageMetaData ( )

Gets the full image metadata generated by the ImageProcessor Engine.

This property will be filled in by the ImageProcessor Engine when returning a processed Image object.

ImageMimeType getImageMimeType ( )

Get the MIME type of this Image object, if an image file representation exists.

OutputColor getImageOutputColor ( )

Get the bits per pixel of the image file representation of this Image object.

The in-memory Bitmap image representation may be different from the image file representation. For example, the in-memory Bitmap may be 4 bytes per pixel, but actual pixel colors used may be only 0x00000000 and 0xFFFFFFFF. This Bitmap can be written out to an image file as a 1 bit-per-pixel packed encoding format.

ImagePerfectionProfile getImagePerfectProfileUsed ( )

Gets the Image Perfection Profile used to generate this Image object.

This property will be filled in by the ImageProcessor Engine when returning a processed Image object.

Float getImagePitch ( )

Gets the pitch of the camera in degrees when the image was taken.

QuickAnalysisFeedback getImageQuickAnalysisFeedBack ( )

Gets the results from calling the doQuickAnalysis method on the ImageProcessor object.

ImageRep getImageRepresentation ( )

Gets the ways in which the image data is represented in this Image object.

An image in this Image object can be represented as an in-memory bitmap, an image file of MIME type ImageMimeType, or both.

Float getImageRoll ( )

Gets the roll of the camera in degrees when the image was taken.

long getImageSize ( )

Returns the size of the image. When the representation is both returns the size of the file.

Returns the size of the image when the image is a file based, buffered, both and bitmap. The size of the bitmap is in pixels, its the product of bitmap height and width and number of bytes per pixel. The size of file is in bytes.

Returns
image size
String getImageSrcID ( )

Gets the imageID if the original input image.

This property will be filled in by the ImageProcessor Engine to the imageID of the input image when returning a processed Image object.

String getImageTag ( )

Gets the application-defined tag for this Image object.

An application could use the ImageTag to distinguish a photo of scenery from a picture of a document.

String getMicrData ( ) throws JSONException

This method will search the image processing metadata for MICR data obtained by processing a check image.

Exceptions
JSONException
Returns
String: The MICR data line from processing a check image.
Rect getTargetFrame ( )

The target frame is a rectangular area confined within the bounds of the image, and represents the ideal area that should be covered by a document. This property will be initialized when image is captured using ImageCaptureView along with one of the Capture Experience.

Returns
Rect
ErrorInfo imageClearBitmap ( )

If a Bitmap representation exists, the bitmap is cleared, and the imageRepresentation property is updated accordingly.

This method will clear and release an existing bitmap representation and update the imageRepresentation property based on whether a file representation also exists, to be either IMAGE_REP_FILE, or IMAGE_REP_UNKNOWN.

Returns
ErrorInfo: (KMC_SUCCESS), or (KMC_ED_ALREADY_CLEAR).
ErrorInfo imageClearFileBuffer ( ) throws KmcException

If a file buffer representation exists, the buffer is cleared, and the imageRepresentation property is updated accordingly.

This method will clear and release an existing file buffer representation and update the imageRepresentation property based on whether a bitmap representation also exists, to be either IMAGE_REP_BITMAP, or IMAGE_REP_UNKNOWN.

Returns
ErrorInfo: (KMC_SUCCESS), or (KMC_ED_BUFFER_ALREADY_CLEARED).
Exceptions
KmcException(KMC_EV_LICENSING)
ErrorInfo imageDeleteFile ( ) throws KmcException, KmcRuntimeException

Deletes the image file in the native storage, and sets the FilePath property to null.

This method deletes the image file and updates imageMimeType and imageRepresentation properties accordingly.

Returns
ErrorInfo: (KMC_SUCCESS), or (KMC_GN_FILE_NOT_FOUND).
Exceptions
KmcRuntimeException(KMC_ED_FILEPATH).
KmcRuntimeException(KMC_ED_DELETE_BUFFERED_FILE).
ErrorInfo imageReadFromFile ( ) throws KmcException, KmcRuntimeException

Reads a bitmap in from an image file of MimeType specified in this object.

This method updates the imageMimeType and imageRepresentation properties accordingly. The bitmap is read in from the file specified in the ImageFilePath property.
The optimized File I/O Engine is used except for PNG file reading.

Note
When reading PNG files, the resulted bitmap will be downscaled if the full-size bitmap does not fit in memory.
The aggressive scaling progression is used, starting with an 0.5 scaling factor on an out-of-memory condition,  and halving it successively until the bitmap fits in memory.
If that automatic downscale occurs ErrorInfo.KMC_ED_IMAGE_IS_SCALED will be returned.

If scaling is desired and/or other than PNG image is read, use the overloaded imageReadFromFile(float imgBitmapScaling)
Returns
ErrorInfo: (KMC_SUCCESS), or (KMC_ED_IMAGE_IS_SCALED).
Exceptions
KmcException(KMC_ED_FILEPATH).
KmcException(KMC_GN_FILE_NOT_FOUND).
KmcException(KMC_GN_OUT_OF_MEMORY).
KmcException(KMC_EV_nnnnn)
See also
imageReadFromFile(float imgBitmapScaling)
ErrorInfo imageReadFromFile ( float  imgBitmapScaling) throws KmcException, KmcRuntimeException

Reads a bitmap in from an image file using the specified scaling factor.

This method reads the bitmap in from the file specified in the ImageFilePath property.
The optimized File I/O Engine is used except for PNG file reading.
This method updates the imageRepresentation property.

Parameters
imgBitmapScalingSpecifies the factor used to scale the bitmap. Must be greater than 0.1 and less than or equal to 1.0.
For example, to scale the image by half, specify a value of 0.5. For no scaling, specify a value of 1.0.
Returns
ErrorInfo: (KMC_SUCCESS).
Exceptions
KmcException(KMC_ED_FILEPATH).
KmcException(KMC_GN_FILE_NOT_FOUND).
KmcException(KMC_GN_OUT_OF_MEMORY).
KmcException(KMC_EV_nnnnn).
KmcException(KMC_ED_IMAGELEAK).
KmcException(KMC_ED_ALREADY_BUFFERED).
KmcRuntimeException(KMC_ED_IMAGE_INVALID_SCALING_FACTOR).

When bitmap scaling is not an option, an alternative is to specify a larger heap size in the application Manifest using the android:largeHeap attribute as shown below:

<application
    android:allowBackup="true"
    android:largeHeap="true"
    android:icon="@drawable/ic_launcher"
    android:name="com.kofax.kmc.kut.utilities.AppContextProvider"
    android:label="@string/app_name"
    android:theme="@style/AppTheme">
    <activity
        android:name="com.example.enginestest.MainActivity"
        android:label="@string/app_name">
        <intent-filter>
            <action android:name="android.intent.action.MAIN"/>
            <category android:name="android.intent.category.LAUNCHER"/>
        </intent-filter>
    </activity>
</application>

Applications should use this option only as a last resort, since enabling large heap size does not guarantee a fixed increase in available memory, because some devices are constrained by their total available memory. It's preferable instead to focus on reducing overall memory usage for improved performance.

ErrorInfo imageReadFromFileBuffer ( ) throws KmcException, KmcRuntimeException

Creates a bitmap from the image file buffer contained in this Image.

The bitmap is created from the file buffer created by a previous call to imageWriteToFileBuffer. This method decompresses the image file buffer into the imageBitmap. After the application calls imageReadFromFileBuffer, the image object will have imageRepresentation=BOTH and imageFileRepresentation=BUFFER.
The optimized File I/O Engine is used except for PNG file reading.

Note
If scaling is desired use the overloaded imageReadFromFileBuffer(float imgBitmapScaling)
Returns
ErrorInfo: (KMC_SUCCESS).
Exceptions
KmcException(KMC_ED_IMAGELEAK).
KmcException(KMC_GN_OUT_OF_MEMORY).
KmcRuntimeException(KMC_ED_NO_BUFFERED_IMAGE).
KmcRuntimeException(KMC_EV_nnnnn).
See also
getImageFileBuffer
imageReadFromFileBuffer(float imgBitmapScaling)
ErrorInfo imageReadFromFileBuffer ( float  imgBitmapScaling) throws KmcException, KmcRuntimeException

Creates a bitmap from the image file buffer contained in this Image.

The bitmap is created from the file buffer created by a previous call to imageWriteToFileBuffer. This method decompresses the image file buffer into the imageBitmap. After the application calls imageReadFromFileBuffer, the image object will have imageRepresentation=BOTH and imageFileRepresentation=BUFFER.
The optimized File I/O Engine is used except for PNG file reading.

Parameters
imgBitmapScalingSpecifies the factor used to scale the bitmap. Must be greater than 0.1 and less than or equal to 1.0.
For example, to scale the image by half, specify a value of 0.5. For no scaling, specify a value of 1.0.
Returns
ErrorInfo: (KMC_SUCCESS).
Exceptions
KmcException(KMC_ED_IMAGELEAK).
KmcException(KMC_GN_OUT_OF_MEMORY).
KmcRuntimeException(KMC_ED_NO_BUFFERED_IMAGE).
KmcRuntimeException(KMC_EV_nnnnn).
KmcRuntimeException(KMC_ED_IMAGE_INVALID_SCALING_FACTOR).
See also
getImageFileBuffer
ErrorInfo imageWriteToFile ( ) throws KmcException, KmcRuntimeException

Writes the bitmap in the imageBitmap property to the file specified in ImageFilePath property.

This method uses the File I/O Engine defined by the FileIOEngine property for writing the bitmap. If the FileIOEngine property is not set, this method uses the default Image Processor File I/O Engine for writing the bitmap.

The imageWriteToFile and imageWriteToFileBuffer methods ("the imageWrite methods") store three EXIF (Exchangeable Image File ) tags for date and time into the output image file or buffer metadata (JPEG and TIFF only):

  • DateTime (code 0x132)
  • DateTimeDigitized (code 0x9004)
  • DateTimeOriginal (code 0x9003)

If the imageReadFromFile() method has been used with this Image object, the imageWrite methods write any JPEG or TIFF date and time stamps from the read image file "as is" into the output file or buffer metadata.

Otherwise, the imageWrite methods write internally generated EXIF metadata into the new JPEG or TIFF file or buffer as follows (all times adjusted to GMT):

The EXIF tag DateTime is generated based on the date and time the image object was created.

EXIF tags DateTimeOriginal and DateTimeDigitized are normally generated the same way as the EXIF tag DateTime, but there is a difference when the given image was created as a result of image processing. In such cases, the imageWrite methods generate the DateTimeOriginal value based on the date/time of the image that was input to image processing. The input image date/time is normally the date/time that image object was created, but could also be derived from JPEG or TIFF image file metadata if the imageReadFromFile() method was used with that image object.

The date/time strings are formatted as yyyy:MM:dd HH:mm:ss, as required by the EXIF standard. This format does not accommodate time zones, so the imageWrite methods use the UTC time that the Image object was created, with the time shifted to compensate for the time zone offset.

However, when the imageReadFromFile() method has been used with the Image object, the JPEG or TIFF date/time stamp from the original image file metadata is carried "as is" into the output compressed data stream.

Note: Date/time metadata output is supported only with the default Image Processor File I/O Engine.

Returns
ErrorInfo: (KMC_SUCCESS), or (KMC_ED_ALTERNATE_FILEIO_ENGINE).
Exceptions
KmcException(KMC_GN_FILE_NOT_FOUND).
KmcException(KMC_ED_FILE_EXISTS).
KmcRuntimeException(KMC_ED_FILEPATH).
KmcRuntimeException(KMC_ED_NOIMAGE).
KmcRuntimeException(KMC_ED_MIMETYPE).
KmcRuntimeException(KMC_ED_BITMAP_WRITE_TO_FILE_FAILED).
ErrorInfo imageWriteToFile ( FileIOEngine  engine) throws KmcException, KmcRuntimeException

Writes the bitmap in the imageBitmap property to the file specified in ImageFilePath property.

This method uses the FileIOEngine passed in as a parameter for writing the bitmap.

The imageWriteToFile and imageWriteToFileBuffer methods ("the imageWrite methods") store three EXIF (Exchangeable Image File ) tags for date and time into the output image file or buffer metadata (JPEG and TIFF only):

  • DateTime (code 0x132)
  • DateTimeDigitized (code 0x9004)
  • DateTimeOriginal (code 0x9003)

If the imageReadFromFile() method has been used with this Image object, the imageWrite methods write any JPEG or TIFF date and time stamps from the read image file "as is" into the output file or buffer metadata.

Otherwise, the imageWrite methods write internally generated EXIF metadata into the new JPEG or TIFF file or buffer as follows (all times adjusted to GMT):

The EXIF tag DateTime is generated based on the date and time the image object was created.

EXIF tags DateTimeOriginal and DateTimeDigitized are normally generated the same way as the EXIF tag DateTime, but there is a difference when the given image was created as a result of image processing. In such cases, the imageWrite methods generate the DateTimeOriginal value based on the date/time of the image that was input to image processing. The input image date/time is normally the date/time that image object was created, but could also be derived from JPEG or TIFF image file metadata if the imageReadFromFile() method was used with that image object.

The date/time strings are formatted as yyyy:MM:dd HH:mm:ss, as required by the EXIF standard. This format does not accommodate time zones, so the the imageWrite methods use the UTC time that the Image object was created, with the time shifted to compensate for the time zone offset.

However, when the imageReadFromFile() method has been used with the Image object, the JPEG or TIFF date/time stamp from the original image file metadata is carried "as is" into the output compressed data stream.

Note: Date/time metadata output is supported only when FileIOEngine.FILE_ENG_KFIL is specified.

Parameters
engineThe FileIOEngine used for writing the bitmap within this image object.
Returns
ErrorInfo: (KMC_SUCCESS), or (KMC_ED_ALTERNATE_FILEIO_ENGINE).
Exceptions
KmcException(KMC_GN_FILE_NOT_FOUND).
KmcException(KMC_ED_FILE_EXISTS).
KmcRuntimeException(KMC_ED_FILEPATH).
KmcRuntimeException(KMC_ED_NOIMAGE).
KmcRuntimeException(KMC_ED_MIMETYPE).
KmcRuntimeException(KMC_ED_BUFFER_EXISTS).
KmcRuntimeException(KMC_ED_BITMAP_WRITE_TO_FILE_FAILED).
ErrorInfo imageWriteToFile ( FileRestriction  fileRestriction) throws KmcException, KmcRuntimeException

Writes the bitmap in the imageBitmap property to the file specified in ImageFilePath property.

This method uses the FILE_ENG_KFIL engine for writing the bitmap.

When the fileRestriction parameter is specified as ANSI_X9, the imageWriteToFile and imageWriteToFileBuffer methods ("the imageWrite methods") behave as follows: The methods store no EXIF (Exchangeable Image File) tags, and no GPS location information. The methods return errors if the image's Mime Type or Output Color or DPI is not compatible with ANSI X9-181 standards. These methods store the Image object creation date and time in the TIFF DateTime field (tag code 0x132).

When the fileRestriction parameter is specified as NONE, output file restrictions are not applied. The behavior is as follows:

The imageWriteToFile and imageWriteToFileBuffer methods ("the imageWrite methods") store three EXIF (Exchangeable Image File ) tags for date and time into the output image file or buffer metadata (JPEG and TIFF only):

  • DateTime (code 0x132)
  • DateTimeDigitized (code 0x9004)
  • DateTimeOriginal (code 0x9003)

If the imageReadFromFile() method has been used with this Image object, the imageWrite methods write any JPEG or TIFF date and time stamps from the read image file "as is" into the output file or buffer metadata.

Otherwise, the imageWrite methods write internally generated EXIF metadata into the new JPEG or TIFF file or buffer as follows (all times adjusted to GMT):

The EXIF tag DateTime is generated based on the date and time the image object was created.

EXIF tags DateTimeOriginal and DateTimeDigitized are normally generated the same way as the EXIF tag DateTime, but there is a difference when the given image was created as a result of image processing. In such cases, the imageWrite methods generate the DateTimeOriginal value based on the date/time of the image that was input to image processing. The input image date/time is normally the date/time that image object was created, but could also be derived from JPEG or TIFF image file metadata if the imageReadFromFile() method was used with that image object.

The date/time strings are formatted as yyyy:MM:dd HH:mm:ss, as required by the EXIF standard. This format does not accommodate time zones, so the the imageWrite methods use the UTC time that the Image object was created, with the time shifted to compensate for the time zone offset.

However, when the imageReadFromFile() method has been used with the Image object, the JPEG or TIFF date/time stamp from the original image file metadata is carried "as is" into the output compressed data stream.

Parameters
fileRestrictionThe FileRestriction used for writing the file.
Returns
ErrorInfo: (KMC_SUCCESS), or (KMC_ED_ALTERNATE_FILEIO_ENGINE).
Exceptions
KmcException(KMC_GN_FILE_NOT_FOUND).
KmcException(KMC_ED_FILE_EXISTS).
KmcRuntimeException(KMC_ED_FILEPATH).
KmcRuntimeException(KMC_ED_NOIMAGE).
KmcRuntimeException(KMC_ED_MIMETYPE).
KmcRuntimeException(KMC_ED_BUFFER_EXISTS).
KmcRuntimeException(KMC_ED_BITMAP_WRITE_TO_FILE_FAILED).
KmcRuntimeException(KMC_ED_FILE_RESTRICTION_MIMETYPE).
KmcRuntimeException(KMC_ED_FILE_RESTRICTION_BITDEPTH).
KmcRuntimeException(KMC_ED_FILE_RESTRICTION_DPI).
ErrorInfo imageWriteToFileBuffer ( ) throws KmcException, KmcRuntimeException

Writes the bitmap in the imageBitmap property to the internal imageFileBuffer.

Writes the imageBitmap to a formatted buffer consisting of the compressed data codes and any header information required to represent the image. This method uses the imageMimeType property to specify the type of compressed data codes and header to use in the file buffer. After the application calls imageWriteToFileBuffer, the image object will have imageRepresentation=BOTH and imageFileRepresentation=BUFFER. The internal imageFileBuffer can be accessed by calling getImageFileBuffer.

The imageWriteToFile and imageWriteToFileBuffer methods ("the imageWrite methods") store three EXIF (Exchangeable Image File ) tags for date and time into the output image file or buffer metadata (JPEG and TIFF only):

  • DateTime (code 0x132)
  • DateTimeDigitized (code 0x9004)
  • DateTimeOriginal (code 0x9003)

If the imageReadFromFile() method has been used with this Image object, the imageWrite methods write any JPEG or TIFF date and time stamps from the read image file "as is" into the output file or buffer metadata.

Otherwise, the imageWrite methods write internally generated EXIF metadata into the new JPEG or TIFF file or buffer as follows (all times adjusted to GMT):

The EXIF tag DateTime is generated based on the date and time the image object was created.

EXIF tags DateTimeOriginal and DateTimeDigitized are normally generated the same way as the EXIF tag DateTime, but there is a difference when the given image was created as a result of image processing. In such cases, the imageWrite methods generate the DateTimeOriginal value based on the date/time of the image that was input to image processing. The input image date/time is normally the date/time that image object was created, but could also be derived from JPEG or TIFF image file metadata if the imageReadFromFile() method was used with that image object.

The date/time strings are formatted as yyyy:MM:dd HH:mm:ss, as required by the EXIF standard. This format does not accommodate time zones, so the imageWrite methods use the UTC time that the Image object was created, with the time shifted to compensate for the time zone offset.

However, when the imageReadFromFile() method has been used with the Image object, the JPEG or TIFF date/time stamp from the original image file metadata is carried "as is" into the output compressed data stream.

Returns
ErrorInfo: (KMC_SUCCESS), or (KMC_ED_ALTERNATE_FILEIO_ENGINE).
Exceptions
KmcRuntimeException(KMC_ED_NOIMAGE).
KmcRuntimeException(KMC_ED_OBJECT_REP_NO_BITMAP).
KmcRuntimeException(KMC_ED_MIMETYPE).
KmcRuntimeException(KMC_ED_ALREADY_BUFFERED).
KmcRuntimeException(KMC_ED_OBJECT_REP_FILE_MISMATCH).
KmcRuntimeException(KMC_ED_NO_MEMORY_FOR_BUFFERED_FILE).
See also
Image::getImageFileBuffer
ErrorInfo imageWriteToFileBuffer ( FileIOEngine  engine) throws KmcException, KmcRuntimeException

Writes the bitmap in the imageBitmap property to the internal imageFileBuffer.

Writes the imageBitmap to a formatted buffer consisting of the compressed data codes and any header information required to represent the image. This method uses the imageMimeType property to specify the type of compressed data codes and header to use in the file buffer. After the application calls imageWriteToFileBuffer, the image object will have imageRepresentation=BOTH and imageFileRepresentation=BUFFER. The internal imageFileBuffer can be accessed by calling getImageFileBuffer.

The imageWriteToFile and imageWriteToFileBuffer methods ("the imageWrite methods") store three EXIF (Exchangeable Image File ) tags for date and time into the output image file or buffer metadata (JPEG and TIFF only):

  • DateTime (code 0x132)
  • DateTimeDigitized (code 0x9004)
  • DateTimeOriginal (code 0x9003)

If the imageReadFromFile() method has been used with this Image object, the imageWrite methods write any JPEG or TIFF date and time stamps from the read image file "as is" into the output file or buffer metadata.

Otherwise, the imageWrite methods write internally generated EXIF metadata into the new JPEG or TIFF file or buffer as follows (all times adjusted to GMT):

The EXIF tag DateTime is generated based on the date and time the image object was created.

EXIF tags DateTimeOriginal and DateTimeDigitized are normally generated the same way as the EXIF tag DateTime, but there is a difference when the given image was created as a result of image processing. In such cases, the imageWrite methods generate the DateTimeOriginal value based on the date/time of the image that was input to image processing. The input image date/time is normally the date/time that image object was created, but could also be derived from JPEG or TIFF image file metadata if the imageReadFromFile() method was used with that image object.

The date/time strings are formatted as yyyy:MM:dd HH:mm:ss, as required by the EXIF standard. This format does not accommodate time zones, so the the imageWrite methods use the UTC time that the Image object was created, with the time shifted to compensate for the time zone offset.

However, when the imageReadFromFile() method has been used with the Image object, the JPEG or TIFF date/time stamp from the original image file metadata is carried "as is" into the output compressed data stream.

Note: Date/time metadata output is supported only when FileIOEngine.FILE_ENG_KFIL is specified.

Parameters
engineThe FileIOEngine used for writing the bitmap within this image object.
Returns
ErrorInfo: (KMC_SUCCESS), or (KMC_ED_ALTERNATE_FILEIO_ENGINE).
Exceptions
KmcRuntimeException(KMC_ED_NOIMAGE).
KmcRuntimeException(KMC_ED_OBJECT_REP_NO_BITMAP).
KmcRuntimeException(KMC_ED_MIMETYPE).
KmcRuntimeException(KMC_ED_ALREADY_BUFFERED).
KmcRuntimeException(KMC_ED_OBJECT_REP_FILE_MISMATCH).
KmcRuntimeException(KMC_ED_NO_MEMORY_FOR_BUFFERED_FILE).
See also
Image::getImageFileBuffer
ErrorInfo imageWriteToFileBuffer ( FileRestriction  fileRestriction) throws KmcException, KmcRuntimeException

Writes the bitmap in the imageBitmap property to the internal imageFileBuffer.

Writes the imageBitmap to a formatted buffer consisting of the compressed data codes and any header information required to represent the image. This method uses the imageMimeType property to specify the type of compressed data codes and header to use in the file buffer. After the application calls imageWriteToFileBuffer, the image object will have imageRepresentation=BOTH and imageFileRepresentation=BUFFER. The internal imageFileBuffer can be accessed by calling getImageFileBuffer.

This method uses the FILE_ENG_KFIL engine for writing the bitmap.

When the fileRestriction parameter is specified as ANSI_X9, the imageWriteToFile and imageWriteToFileBuffer methods ("the imageWrite methods") behave as follows: The methods store no EXIF (Exchangeable Image File) tags, and no GPS location information. The methods return errors if the image's Mime Type or Output Color or DPI is not compatible with ANSI X9-181 standards.

When the fileRestriction parameter is specified as NONE, the behavior is as follows:

The imageWriteToFile and imageWriteToFileBuffer methods ("the imageWrite methods") store three EXIF (Exchangeable Image File ) tags for date and time into the output image file or buffer metadata (JPEG and TIFF only):

  • DateTime (code 0x132)
  • DateTimeDigitized (code 0x9004)
  • DateTimeOriginal (code 0x9003)

If the imageReadFromFile() method has been used with this Image object, the imageWrite methods write any JPEG or TIFF date and time stamps from the read image file "as is" into the output file or buffer metadata.

Otherwise, the imageWrite methods write internally generated EXIF metadata into the new JPEG or TIFF file or buffer as follows (all times adjusted to GMT):

The EXIF tag DateTime is generated based on the date and time the image object was created.

EXIF tags DateTimeOriginal and DateTimeDigitized are normally generated the same way as the EXIF tag DateTime, but there is a difference when the given image was created as a result of image processing. In such cases, the imageWrite methods generate the DateTimeOriginal value based on the date/time of the image that was input to image processing. The input image date/time is normally the date/time that image object was created, but could also be derived from JPEG or TIFF image file metadata if the imageReadFromFile() method was used with that image object.

The date/time strings are formatted as yyyy:MM:dd HH:mm:ss, as required by the EXIF standard. This format does not accommodate time zones, so the the imageWrite methods use the UTC time that the Image object was created, with the time shifted to compensate for the time zone offset.

However, when the imageReadFromFile() method has been used with the Image object, the JPEG or TIFF date/time stamp from the original image file metadata is carried "as is" into the output compressed data stream.

Parameters
fileRestrictionThe FileRestriction used for writing the file buffer.
Returns
ErrorInfo: (KMC_SUCCESS), or (KMC_ED_ALTERNATE_FILEIO_ENGINE).
Exceptions
KmcRuntimeException(KMC_ED_NOIMAGE).
KmcRuntimeException(KMC_ED_OBJECT_REP_NO_BITMAP).
KmcRuntimeException(KMC_ED_MIMETYPE).
KmcRuntimeException(KMC_ED_ALREADY_BUFFERED).
KmcRuntimeException(KMC_ED_OBJECT_REP_FILE_MISMATCH).
KmcRuntimeException(KMC_ED_NO_MEMORY_FOR_BUFFERED_FILE).
KmcRuntimeException(KMC_ED_FILE_RESTRICTION_MIMETYPE).
KmcRuntimeException(KMC_ED_FILE_RESTRICTION_BITDEPTH).
KmcRuntimeException(KMC_ED_FILE_RESTRICTION_DPI).
See also
Image::getImageFileBuffer
void setImageBarCodes ( List< BarCodeResult imageBarCodes)

Sets an array of BarCodeResult objects representing bar codes found on this image.

void setImageBitmap ( Bitmap  imgBitmap) throws KmcRuntimeException

Set the Bitmap representation of this Image object.

If the Image object already has a reference to an Image file, the reference is removed, but the associated Image file is left alone and orphaned. Use the imageDeleteFile() method to explicitly delete a referenced Image file. You must first call the imageDeleteFile() before setting a new bitmap, if the current Image Representation is either IMAGE_REP_FILE, or IMAGE_REP_BOTH. Failure to do so will generate a KmcRuntimeException.

Parameters
imgBitmapMust be set to a valid Android Bitmap object.
Exceptions
KmcRuntimeException(KMC_ED_OBJECT_REP_FILE_MISMATCH).
void setImageClassifyResults ( List< ImageClassificationResult imgClassifyResults)

Sets an array of ImageClassificationResult objects representing the result of classifying this image.

This property will be filled in by the Classifier Engine when returning a classified Image object.

void setImageCreateDateTime ( String  imgCreateDateTime)

Sets the date and time the image was created, in ISO 8601 format.

  • Example of how to convert a Java Date object to ISO 8601 formatted string:
    String imgCreateDateTime = DateFormatUtils.ISO_DATETIME_TIME_ZONE_FORMAT.format(new Date());
    Exceptions
    KmcRuntimeException(KMC_ED_INVALID_ISO_DATE_TIME_FORMAT).
void setImageDPI ( int  imgDPI)

Set the resolution of this image in Dots Per Inch.

The ImageDPI property will be set by the Image Processor Engine, to represent the output DPI of a processed image. The DPI may also be set on a call to imageReadFromFile() method, if it can be determined based on the image file header. If the DPI is not known or never set, the imageDPI property defaults to null. If the imageWriteToFile() is called, a default value of 72 DPI will be used when writing an in-memory bitmap to an image file, if none is specified.

Parameters
imgDPIThe Dots Per Inch resolution of the image represented by this image object. The minimum imgDPI value allowed is 25. Setting a value less than 25 will result in an KmcRuntimeException being thrown.
Exceptions
KmcRuntimeException(KMC_ED_INVALID_DPI) if imgDPI < MIN_DPI_VALUE.
void setImageFilePath ( String  imgFilePath) throws KmcRuntimeException

Set the path to an image file which this Image object will represent.

This image file must be one of the MimeTypes included in the ImageMimeType enumeration. If the image file exists, and the Image object already has a Bitmap allocated, a KmcRuntimeException is thrown. To avoid this, call imageClearBitmap() method first. Only image files that are stored locally on the file system of the mobile device are supported. Image file paths which include a web address are not supported.

Parameters
imgFilePathA file path representing an image file in the local file system of the mobile device.
Exceptions
NullPointerException(imgFilePath parameter is null).
KmcRuntimeException(KMC_ED_UNRECOGNIZED_MIME_TYPE).
KmcRuntimeException(KMC_ED_OBJECT_REP_FILE_MISMATCH).
void setImageJpegQuality ( int  imgJpegQuality)

Set the JPEG image quality for JPEG image files.

Parameters
imgJpegQualityRepresents a JPEG compression quality value, where lower numbers indicate higher compression (smaller size), but lower image quality. Higher JPEG quality numbers indicate lower compression (larger size), but better image quality. Valid quality values are 1 to 100.

Note: Compression values less than 80 are not recommended for images that are intended for further image processing.

void setImageMimeType ( ImageMimeType  imgMimeType)

Set the MIME type of this Image object, if an image file representation exists.

void setImageOutputColor ( OutputColor  imgOutputColor)

Set the bits per pixel of the image file representation of this Image object.

The in-memory Bitmap image representation may be different from the image file representation. For example, the in-memory Bitmap may be 4 bytes per pixel (ARGB_8888), but actual pixel colors used may be only 0x00000000 and 0xFFFFFFFF. This Bitmap can be written out to an image file as a 1 bit-per-pixel packed encoding format. The MIME type for the image file must support the bits-per-pixel value specified.

void setImageTag ( String  imgTag)

Sets the application-defined tag for this Image object.

An application could use the ImageTag to distinguish a photo from a picture of a document.

void setMicrData ( String  micrData) throws NullPointerException

Set the MICR data of the check image.

Exceptions
NullPointerException(micrData parameter is null)
void setTargetFrame ( Rect  targetFrame)

Set target frame data cropping purposes.

See also
getTargetFrame()

Default value is null.

Member Data Documentation

final int DEFAULT_JPEG_QUALITY = 90
static
final int MAX_JPEG_QUALITY = 100
static
final float MAX_SCALING_FACTOR = 1.0f
static
final int MIN_JPEG_QUALITY = 1
static
final float MIN_SCALING_FACTOR = 0.1f
static

The documentation for this class was generated from the following file:
Untitled Document © 2017 Atalasoft, Inc., 116 Pleasant St, Suite 321, Easthampton, MA 01027, U.S.A. All rights reserved. Use is subject to license terms.