The Image Processor Class. More...
#import <kfxKIPImageProcessor.h>
Instance Methods | |
| (int) | - specifyProcessedImageFilePath: |
| Specify a file path for use with the object. More... | |
| (NSString *) | - getProcesedImageFilePath |
| Get the current processed image file path. More... | |
| (int) | - processImage: |
| Use the processImage method to process the specified image. More... | |
| (int) | - processImage:withConfiguration: |
| Use the processImage method to process the specified image. More... | |
| (int) | - doQuickAnalysis:andGenerateImage: |
| Use the quick analysis method to check image quality. More... | |
| (int) | - doQuickAnalysis:andGenerateImage:withSettings: |
| (void) | - cancelProcessing |
| Use the cancel processing method to stop image processing. More... | |
| (void) | - SessionCreate |
| Begin an AppStats session. More... | |
| (void) | - SessionDismiss |
| End an AppStats session. More... | |
Class Methods | |
| (kfxKENImageProcessor *) | + instance |
| The Image Processor Engine factory method. More... | |
Properties | |
| id< kfxKIPDelegate > | delegate |
| kfxKIPDelegate that notifies you about progress and completion of image processing operations More... | |
| kfxKEDImagePerfectionProfile *imagePerfectionProfile | DEPRECATED_ATTRIBUTE |
| Image Perfection Profile specifies advanced Image Processing options. More... | |
| KEDImageRepresentation | processedImageRepresentation |
| Set the desired output image representation format. More... | |
| KEDImageMimeType | processedImageMimetype |
| Set the the file storage mimetype configuration. More... | |
| int | processedImageJpegQuality |
| Set the processed Image jpeg Quality. More... | |
| kfxKEDBasicSettingsProfile *basicSettingsProfile | DEPRECATED_ATTRIBUTE |
| Basic settings profile specifies Image Processing options. More... | |
Detailed Description
The Image Processor Class.
Framework: libKfxEngines
Import suggestion: #import <kfxLibEngines/kfxEngines.h>
Relevant Header File: kfxKIPImageProcessor.h
An instance of this class contains methods to process images. It holds the profile that specifies the kind of image processing to perform based on a selected image processing profile. Use the methods on this object to do standard image processing, perform a quick quality analysis, and to find a signature in the image for a particular area.
Licensing**
This is a license protected class. Certain methods in this object are protected by a license mechanism. If you attempt to use these methods without setting the license, then you will receive the KMC_IP_LICENSE_INVALID error code. Refer to the method descriptions to determine what methods are license protected. In order to set your license, you need to use the setMobileSDKLicense method on the kfxKUTLicensing object. Example code is provided to show you how to set your license, which can be found in the kfxKUTLicensing class of the kfxUtilities framework.
Method Documentation
◆ cancelProcessing()
| - (void) cancelProcessing |
Use the cancel processing method to stop image processing.
Use the cancelProcessing method to cancel an image processing operation that is underway. In, this way, the app can respond to low-memory events or, for any reason, the app user manually stops processing while the image is being processed in background. To do this, asynchronously call a cancel method in the Image Processor engine. Note that there may be a delay between cancelling and the imageOut delegate because the image processor will only cancel the balance of processing tasks on functional boundaries. The image out event will indicate that the processing was cancelled if the image processing operation was incomplete.
The library ignores the cancelProcessing call if the operation has already completed or hasn't started yet. If you cancel processing beforehand, the library will not cancel immediately if you then call processImage.
Background image processing and the cancel operation are both asynchronous. Depending on the current percentage last reported by the progress delegate, the image processing operation may be nearly complete. Therefore, the library may not necessarily cancel an operation, and the cancel error status may not occur. If the operation is cancelled, the imageOut delegate will indicate the KMC_EV_USER_ABORT status. In this case, there will be no image object included with the imageOut delegate.
The cancelProcessing method will cancel either a quick analysis or an image processing operation.
◆ doQuickAnalysis:andGenerateImage:()
| - (int) doQuickAnalysis: | (kfxKEDImage *) | imageToAnalyze | |
| andGenerateImage: | (bool) | generateRefImage | |
Use the quick analysis method to check image quality.
Use this method to specify the image upon which you want to perform a quick analysis. The image processor will check image quality and determine the page edges of a document in the image.
The doQuickAnalysis method does not use a profile. The library uses an internally generated opString, and ignores the basic settings profile and the image perfection profile set in the image processor object.
License Required: this is a licensed method. You cannot use this method until you have set a valid SDK license. In order to set your license, you need to use the setMobileSDKLicense method on the kfxKUTLicensing object. An example of setting your license can be found in the licensing class.
The method returns KMC_SUCCESS if the process starts without any error. In this case you should expect multiple analysis process progress delegate calls to indicate the progress of the analysis. You should never make any assumptions about completion of the process when you get to 100% completion, because the library performs several post process steps and then calls the analysisComplete delegate. You should always check the status in the analysis complete delegate to know if the process completed without error.
If the call to doQuickAnalysis method does not return KMC_SUCCESS, then the library will not have stored the kfxKEDQuickAnalysisFeedback object, and you will not receive any progress delegate calls nor a analysisComplete delegate call. Therefore, you should always check the return value to make sure you have correctly initialized objects for the process and analysis starts up ok.
Quick analysis always returns a kfxKEDImage in the analysisComplete delegate, and this is a reference to the same input image given to quick analysis with the imageToAnalyze parameter. When Quick Analysis completes without error, it stores a kfxKEDQuickAnalysisFeedback object in the input image for your use. If you request a reference image, by setting the generateRefImage to true, then the library returns a UIImage reference in the kfxKEDQuickAnalysisFeedback object.
Quick Analysis Results are always stored in the kfxKEDQuickAnalysisFeedback object in the input image specified with the imageToAnalyze parameter. Then you can decide what to do with the results. You should examine the various settings in the kfxKEDQuickAnalysisFeedback object, to see if the image is blurry, over saturated, under saturated or not. The library also sets the bounding tetragon corners and side equasions for the page boundaries in the feedback object and the metadata. Then if the image looks good, you can also display the reference UIImage * if you requested one. You could display this image for user confirmation, and then a new picture could be taken if the user decides he doesn't like the results, or the green bordered image of the page seems incorrect.
Otherwise, if your user accepts the image, you could then process the image using a standard processImage call. When you do so, if you want to crop to the page detection referenced by the quick analysis process, you should use a basic settings profile, and set the doCrop setting to KED_CROP_WITH_QUICK_ANALYSIS_RESULTS, and your image processing will complete sooner than if you did normal processing because the library already knows the page boundaries.
Note: The library ignores any supplied profiles and uses internal settings instead. This data is returned in the quick analysis feedback object in the input imageToAnalyze object.
The analysisComplete delegate returns your input image, and everything in it is retained.
When the processing completes normally, the library sets the following image object properties:
imageQuickAnalysisFeedback, set to an object created by the analysis, indicating the results, and a reference image if requested. imageMetaData, to the quick analysis metadata created by the image processor for quick analysis.
Quick analysis generates large autorelease objects. If this method is to be called many times, it is recommended to wrap the calls with directive.
- Parameters
-
imageToAnalyze the actual input image object that you want to check generateRefImage is a bool, when set to true, causes the image processor to return a native UIImage object. This image incluces a green border around the page boundaries. You can use this image to detect the correct orientation and edges, to decide if the image should be used for further processing or not.
- Returns
- This method returns KMC_SUCCESS when image processing started without error. Otherwise it may return one of these error codes if processing was not started. No delegates are generated if the method returns an error.
KMC_IP_LICENSE_INVALID if you have not set a valid license yet. KMC_ED_NOIMAGE If you did not include an image in the input image object.
KMC_ED_FILEPATH If the image object is represented by a file, but the file path is missing.
KMC_ED_NONEXISTENT_FILE If the file name in the input object was specified so that the image representation is set to IMAGE_REP_FILE, an then the file used to represent the image is later deleted. The the library returns this error if you try to process it.
KMC_IP_NO_REPRESENTATION If the image representation in the input image object is invalid, and not set to IMAGE_REP_FILE, or IMAGE_REP_BITMAP or BOTH. This indicates that there is no image to process. This is returned even if you set a file path to a non-existant file.
KMC_ED_NO_MEMORY_FOR_METADATA if memory could not be allocated to store image metadata.
KMC_ED_IMAGE_COLOR_SPACE If the library could not create a color space reference, usually a system resource issue.
KMC_ED_IMAGE_CONTEXT, If an image bitmap could not be created, normally caused by a resource issue.
- See also
- Use - cancelProcessing to cancel an ongoing quick analysis process if necessary.
◆ doQuickAnalysis:andGenerateImage:withSettings:()
| - (int) doQuickAnalysis: | (kfxKEDImage *) | imageToAnalyze | |
| andGenerateImage: | (bool) | generateRefImage | |
| withSettings: | (kfxKEDQuickAnalysisSettings *) | settings | |
◆ getProcesedImageFilePath()
| - (NSString *) getProcesedImageFilePath |
Get the current processed image file path.
Use this method to retrieve the current file path associated with this object. In some cases, the file name may not have been set if the specifyProcessedImageFilePath method returned an error.
◆ instance()
| + (kfxKENImageProcessor*) instance |
The Image Processor Engine factory method.
Use this method to obtain a singleton object reference to the kfxKENImageProcessor.
◆ processImage:()
| - (int) processImage: | (kfxKEDImage *) | DEPRECATED_ATTRIBUTE |
Use the processImage method to process the specified image.
Use this method when you want to perform standard image processing on the image supplied with the method. The library processes the image using the processing options contained in the profile you specified. You can specify either a basic settings profile or an image perfection profile. If the input image representation is file based, and a bitmap is not supplied, the library will load and process the image from the file in the image object. If the image is represented by a bitmap, then the library uses that image, even if the image representation indicates both (bitmap and file).
License Required: this is a licensed method. You cannot use this method until you have set a valid SDK license. In order to set your license, you need to use the setMobileSDKLicense method on the kfxKUTLicensing object. You must obtain a valid license from Kofax in order to use licensed methods. An example of setting your license can be found in the licensing class.
This method generates a brand new kfxKEDImage object, if the image processing completes without error. The library notifies you by calling the imageOut delegate. The output image object does not retain much from the input image.
When the processing completes normally, the library sets the following output image object properties:
imageMimeType, to the MIMETYPE_UNKNOWN setting.
imageBitMap, to the new processed bitmap.
imageRepresentation, to IMAGE_REP_BITMAP, because the bitmap is stored.
imageSourceID, to the imageID of the input image.
imageMetaData, to the metadata created by the image processor.
imagePerfectionProfileUsed or basicSettingsProfileUsed, to the one that was used to produce the output image.
imageGPSLat, to the preserved latitude of the source input file.
imageGPSLon, to the preserved longitude of the source input file.
imageFileOutputColor, to the new color definition of the output image generated.
imageHeight, to the height of the new output image.
imageWidth, to the width of the new output image.
All other image object properties are set to the default.
- Parameters
-
imageToProcess the actual input image object that you want to process
- Returns
- This method returns KMC_SUCCESS when the image processing was started up successfully. Several error codes are returned for this method when the image processing request could not be started, due to such things as memory limitations. In these cases, the method generates no final completion notification by calling your imageOut delegate. But, if the library returns KMC_SUCCESS, then image processing has started successfully. Your imageOut delegate is called after the image processing completes, in which case a processing error may be indicated in the delegate. So you should always check this return value to detect if you should expect progress delegate calls or completion delegate calls. One of these error codes may be returned immediately, in which case the background processing is not started.
The possible error codes are:
KMC_IP_LICENSE_INVALID if you have not set a valid license yet. KMC_ED_NO_MEMORY_FOR_METADATA if memory could not be allocated to store image metadata.
KMC_ED_NOIMAGE if you did not include an image in the input image object.
KMC_IP_NO_PROFILE if you forgot to include a profile, either a basic settings or perfection profile.
KMC_ED_FILEPATH if the image object is represented by a file, but the file path is missing.
KMC_ED_NONEXISTENT_FILE If the file name in the input object was set to the name of a non-existant file, and you try to process it.
KMC_IP_NO_REPRESENTATION if the image representation in the input image object is invalid.
KMC_ED_IMAGE_COLOR_SPACE if the library could not create a color space reference, usually a system resource issue.
KMC_ED_IMAGE_CONTEXT if an image bitmap could not be created, normally caused by a resource issue.
- See also
- Use - cancelProcessing to cancel an image processing operation if necessary.
- Deprecated:
- as of 3.3, replaced by kfxKENImageProcessor::processImage:withConfiguration:
◆ processImage:withConfiguration:()
| - (int) processImage: | (kfxKEDImage *) | imageToProcess | |
| withConfiguration: | (KFXImageProcessorConfiguration *) | configuration | |
Use the processImage method to process the specified image.
Use this method when you want to perform image processing on the image supplied with the method. The library processes the image using the processing options contained in the configuration you specified. If the input image representation is file based, and a bitmap is not supplied, the library will load and process the image from the file in the image object. If the image is represented by a bitmap, then the library uses that bitmap, even if the image representation indicates both (bitmap and file).
License Required: this is a licensed method. You cannot use this method until you have set a valid SDK license. In order to set your license, you need to use the setMobileSDKLicense method on the kfxKUTLicensing object. An example of setting your license can be found in the licensing class.
This method generates a brand new kfxKEDImage object, if the image processing completes without error. The library notifies you by calling the imageOut delegate.
When the processing completes normally, the library sets the following output image object properties:
imageMimeType, to the MIMETYPE_UNKNOWN setting.
imageBitmap, to the new processed bitmap.
imageRepresentation, to IMAGE_REP_BITMAP.
imageSourceID, to the imageID of the input image.
imageMetaData, to the metadata created by the image processor.
imagePerfectionProfileUsed or basicSettingsProfileUsed, to the one that was used to produce the output image.
imageGPSLat, to the preserved latitude of the source input file.
imageGPSLon, to the preserved longitude of the source input file.
imageFileOutputColor, to the new color definition of the output image generated.
imageHeight, to the height of the new output image.
imageWidth, to the width of the new output image.
All other image object properties are set to the default.
- Parameters
-
imageToProcess the actual input image object that you want to process configuration the configuration containing the image processing operations to be performed
- Returns
- This method returns KMC_SUCCESS when the image processing was started up successfully. Several error codes are returned for this method when the image processing request could not be started, due to such things as memory limitations. In these cases, the method generates no final completion notification by calling your imageOut delegate. But, if the library returns KMC_SUCCESS, then image processing has started successfully. Your imageOut delegate is called after the image processing completes, in which case a processing error may be indicated in the delegate. So you should always check this return value to detect if you should expect progress delegate calls or completion delegate calls. One of these error codes may be returned immediately, in which case the background processing is not started.
- See also
- Use - cancelProcessing to cancel an image processing operation if necessary.
◆ SessionCreate()
| - (void) SessionCreate |
Begin an AppStats session.
This method begins a new AppStats session. It creates a new instance object and initializes it with the current time. In combination with SessionDismiss, it allows specified log information to be bracketed with begin and end times.
◆ SessionDismiss()
| - (void) SessionDismiss |
End an AppStats session.
This method ends an AppStats session. It updates a previously created instance object with a dismissal time.
◆ specifyProcessedImageFilePath:()
| - (int) specifyProcessedImageFilePath: | (NSString *) | fullFilePath |
Specify a file path for use with the object.
Use this method to specify the fully qualified path to a file name that you want to contain the output processed image. Usually this file should not already exist. You should always check for returned error codes because this specifyProcessedImageFilePath method returns errors for certain cases. When this method returns an error, the libary will not save the file path. The valid file path extensions are: jpg, jpeg, tif, tiff, png and their upper-case equivalents.
If the file name extension is valid, then the library sets up the imageMimetype setting for you.
This value is only used when the processedImageRepresentation is set to IMAGE_REP_FILE or IMAGE_REP_BOTH.
- Returns
- KMC_ED_OBJECT_REP_BITMAP_MISMATCH, when you try to set a file name for an existing file, when there is already a bitmap set for the object.
- KMC_ED_FILE_EXTENSION, when you try to set a file name with an illegal file extension.
Property Documentation
◆ delegate
|
readwriteatomicweak |
kfxKIPDelegate that notifies you about progress and completion of image processing operations
You must set this delegate to self in order for your app to receive the processing delegate calls during image processing.
◆ DEPRECATED_ATTRIBUTE [1/2]
|
readwriteatomicretain |
Image Perfection Profile specifies advanced Image Processing options.
An instance of this class contains the advanced image processing options to perform on an image. These settings are a superset of what is possible with basic settings profiles. These settings may have originated from a KFS Server, a Total Agility server or your own application. This object contains more complicated image processing settings, and allows two methods of specifying these settings: with an image processing Operations string, or a settings file. If both an ImagePerfectionProfile and a BasicSettingsProfile are supplied to an image object, the ImagePerfectionProfile takes precedence, while ignoring the basic settings. If you include both a settings file and an operations string, the engine includes both. Even though you should try to avoid use of conflicting settings to get expected consistent results, if there are conflicts in one or both of the settings, the last setting in a string or file takes precedence. For instance if you requested a grayscale output and then a bitonal output in the same settings string, then the image would be bitonal.
- Deprecated:
- Deprecated in SDK 3.3. Please use KFXImageProcessorConfiguration instead.
◆ DEPRECATED_ATTRIBUTE [2/2]
|
readwriteatomicretain |
Basic settings profile specifies Image Processing options.
An instance of this class contains the simple image processing options that you want to perform on an image. These define the standard crop, deskew and rotation options. You can also use this object to specify the output image DPI and the desired output image color. Specify the output color by setting outputBitDepth to 1 for bitonal images, 8 for grayscale, or 24 for color. The image processor outputs a new image with the bitmap in one of these colors. The cropping Tetragon defines the bounding corner points of an area of an image that you want to crop, and thereby override automatic page detection.
If the outputDPI is >= 300 DPI, and the outputBitDepth is 1, then the image processing includes enhanced binarization. Otherwise it uses standard binarization.
- Deprecated:
- Deprecated in SDK 3.3. Please use KFXImageProcessorConfiguration instead.
◆ processedImageJpegQuality
|
readwriteatomicassign |
Set the processed Image jpeg Quality.
This property indicates the desired level of quality for writing a JPEG image when you want the image processor to automatically save the image to a file. It must be set to a value from 1 to 100. The higher the number the less compression is used, the higher the quality and the larger the output file size in bytes. A low setting would highly compress the output image, and some quality is sacrificed, but the file size is smaller. Valid for color output file format only, and ignored for others.
This value is only used when the processedImageRepresentation is set to IMAGE_REP_FILE or IMAGE_REP_BOTH. Default: 90
◆ processedImageMimetype
|
readwriteatomicassign |
Set the the file storage mimetype configuration.
Use this setting to specify the mimetype of the output file generated by the image processor when you specified IMAGE_REP_FILE or IMAGE_REP_BOTH in the processedImageRepresentation.
The library automatically sets this property for you if you use the specifyProcesedImageFilePath method and use a standard file extension recognized by the library. Otherwise, you should set this before calling processImage. This property is write/read because you can decide what mimetype you want before starting image processing.
Related Properties for file storage:
- processedImageRepresentation property
- processedImageMimetype property
- processedImageJpegQuality property
- specifyProcessedImageFilePath method
Default: MIMETYPE_UNKNOWN- See also
- KEDImageMimeType enumeration
◆ processedImageRepresentation
|
readwriteatomicassign |
Set the desired output image representation format.
Use this property to specify the representation of the output processed image object. When image processing completes, the library calls the imageOut delegate and provides the output image object. This property directs the image processor to create the object with the image as a bitmap, a file or both. You need to specify a fully qualified file path for the file format representation.
As opposed to using the imageWriteToFile in the kfxKEDImage object, which is a synchronous method, you can use the property to write the file as part of a background process in the image processor when you set this property to IMAGE_REP_FILE.
The image processor has four processedImage properties that specify how the file should be written when the image representation is set to IMAGE_REP_FILE or IMAGE_REP_BOTH. When the image representation is set to IMAGE_REP_BITMAP, the other three related file properties are unused.
If you set the processedImageRepresentation to IMAGE_REP_NONE, the library still generates an output image object, but it will contain no image. However, the image object will contain the image metadata associated with the processing operation.
You must always set this property to specify your desired output image format, or the default will be used.
Related Properties for file storage:
- processedImageRepresentation property
- processedImageMimetype property
- processedImageJpegQuality property
- specifyProcessedImageFilePath method
Default: IMAGE_REP_BITMAP
- See also
- specifyProcessedImageFilePath
-
processedImageRepresentation property
-
processedImageMimetype property
-
processedImageJpegQuality property
The documentation for this class was generated from the following file: