Atalasoft MobileImage API Reference
Instance Methods | Class Methods | Properties | List of all members
kfxKUIImageCaptureControl Class Reference

This class renders the camera preview to the screen and returns an image. More...

#import <kfxKUIImageCaptureControl.h>

Inheritance diagram for kfxKUIImageCaptureControl:

Instance Methods

(int) - takePicture
 Begins the image capture process. More...
 
(int) - forceTakePicture
 Begins the image capture process and ignores all capture constraints. More...
 
(int) - forceTakePicture:
 Begins the image capture process and ignores all capture constraints. More...
 
(int) - doContinuousMode:
 Starts or stops the continuous capture of images. More...
 
(int) - setImageResolution:
 Sets the desired preset for image capture. More...
 
(BOOL) - canSetResolution:
 Returns whether the given preset can be used. More...
 
(void) - SessionCreate
 Begin an AppStats session. More...
 
(void) - SessionDismiss
 End an AppStats session. More...
 
(void) - stopCapture
 Stops taking a picture. More...
 

Class Methods

(void) + initializeControl
 This message initializes the control and must be sent to the class before it is used. More...
 

Properties

int stabilityDelay
 The current stability delay. More...
 
kfxKUIFlashSetting flash
 The current camera flash mode. More...
 
kfxKUIFrameimageFrame
 The kfxKUIFrame object. More...
 
BOOL useVideoFrame
 Whether the video frame is retured, or a full-resolution image is captured. More...
 
BOOL automaticallyEnablesStillImageStabilization
 A Boolean value that indicates whether still image stabilization should be automatically enabled when available. More...
 
kfxKUIPageDetect pageDetectMode DEPRECATED_ATTRIBUTE
 Gets or sets the the page detection behavior of the control. More...
 
int levelThresholdPitch
 The threshold used to determine if the device is level. More...
 
int levelThresholdRoll
 The threshold used to determine if the device is level. More...
 
int deviceDeclinationPitch
 The reference pitch that indicates what angle means that the device is level. More...
 
int deviceDeclinationRoll
 The reference roll that indicates what angle means that the device is level. More...
 
CGSize imagePreviewSize
 Gets the camera preview resolution. More...
 
int pageAreaForDetection DEPRECATED_ATTRIBUTE
 The minimum area that a page must cover before it is detected as a page. More...
 
CGPoint defaultFocusPoint
 Gets the default camera focus point. More...
 
CGPoint focusPoint
 The camera focus point. More...
 
IBOutlet id< kfxKUIImageCaptureControlDelegatedelegate
 A delegate to receive messages from the control. More...
 
CMMotionManager * motionManager
 The motion manager being used to detect the levelness of the device. More...
 
kfxKUIGPSUsageLimits gpsUsageLimits
 gpsUsageLimits - controls whether GPS location information is captured with the image. More...
 

Detailed Description

This class renders the camera preview to the screen and returns an image.

This class is responsible for rendering the camera preview and provides visual level and stability feedback to guide the user to take a clear, legible photo of a document.

Method Documentation

- (BOOL) canSetResolution: (NSString *)  resolution

Returns whether the given preset can be used.

The preset values accepted by this method are the same session presets defined by Apple in AVFoundation.

The camera session must be active before this method can return correct results. If your instance of the ImageCaptureControl is being attached to your view implicitly by a storyboard or Interface Builder, then the earliest place you should query this method is in your view's viewDidAppear method.

If you are explicitly attaching an ImageCaptureControl to your view in code, then you can query this method at any point after, as long as the control remains attached to the active view hierarchy.

Parameters
resolutionA session preset
See also
setImageResolution
- (int) doContinuousMode: (BOOL)  enable

Starts or stops the continuous capture of images.

Calling this method will start or stop the continuous capture of images. Images will automatically be captured when levelness and stability criteria are satisfied. Between each image capture event, the device must be tilted away from its set device declination. This signals the device to capture a new image when levelness and stability criteria are again satisfied.

Continuous mode can only be enabled when the levelness thresholds for pitch and roll are less than 75 degrees.

Parameters
enableYES to start continuous mode, NO to stop it.
Return values
KMC_SUCCESSThe continuous mode was set successfully.
KMC_EV_LICENSINGThe continuous mode was not set successfully, and returns the licensing error code.
- (int) forceTakePicture

Begins the image capture process and ignores all capture constraints.

Calling this method will stat the image capture process, but constraints like levelness, stability, and page detection will be ignored. The control will attempt to take a picture as quickly as possible. As with the standard takePicture method, the delegate will receive a imageCaptureControl:imageCaptured: message for each captured iamge.

Return values
KMC_SUCCESSThe control will attempt to capture a picture.
KMC_EV_LICENSINGThe control did attempt attempt to capture a picture due to a licensing error.
- (int) forceTakePicture: (BOOL)  waitForFocus

Begins the image capture process and ignores all capture constraints.

Calling this method will start the image capture process, but constraints like levelness, stability, and page detection will be ignored. The control will attempt to take a picture as quickly as possible. As with the standard takePicture method, the delegate will receive a imageCaptureControl:imageCaptured: message for each captured iamge.

Parameters
waitForFocusYES to check focus check Criteria, NO to take picture without checking any crieteria.
Return values
KMC_SUCCESSThe control will attempt to capture a picture.
KMC_EV_LICENSINGThe control did not attempt to capture a picture due to a licensing error.
+ (void) initializeControl

This message initializes the control and must be sent to the class before it is used.

This message initializes the control for use and must be sent to the class before it is used. It is ok to send the message more than once. A common way to do this is in your UIViewController subclasses initialize or init methods.

- (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.

- (void) SessionDismiss

End an AppStats session.

This method ends an AppStats session. It updates a previously created instance object with a dismissal time.

- (int) setImageResolution: (NSString *)  resolution

Sets the desired preset for image capture.

Sets the desired preset for image capture. The actual resolution of a captured image may be reversed from what is given (e.g. a 960x1280 image may be returned for a 1280x960 request). Presets may select different image resolutions depending on device.

After calling this method, the kfxUIImageCaptureControl instance may resize itself.

Note: The AVCaptureControlInputPriority preset is not supported.

Parameters
resolutionA session preset
Return values
KMC_SUCCESSThe desired preset was accepted
KMC_GN_UNSUPPORTED_OPERATIONThe desired preset is not supported
See also
useVideoFrame
- (void) stopCapture

Stops taking a picture.

This can be used in continuous mode as well to stop taking pictures

- (int) takePicture

Begins the image capture process.

Calling this method will start the process of monitoring the various sensors to determine when a level, focused, and non-blurry shot of the document can be taken. The delegate will receive a imageCaptureControl:imageCaptured: message for each captured image.

Return values
KMC_SUCCESSThe control will attempt to capture a picture.
KMC_EV_LICENSINGThe control did attempt attempt to capture a picture due to a licensing error.

Property Documentation

- (BOOL) automaticallyEnablesStillImageStabilization
readwritenonatomicassign

A Boolean value that indicates whether still image stabilization should be automatically enabled when available.

If Image Stabilization is supported by device, it may be applied to reduce blur commonly found in low light photos. When stabilization is enabled, still image captures incur additional latency.

This setting is applicable only for a full-resolution image capture mode when useVideoFrame is set to NO. For devices with no stabilization support this will do nothing.

The default value is YES which mean stabilization will be automatically enabled when available.

- (CGPoint) defaultFocusPoint
readatomicassign

Gets the default camera focus point.

See also
focusPoint
- (IBOutlet id<kfxKUIImageCaptureControlDelegate>) delegate
readwritenonatomicweak

A delegate to receive messages from the control.

A property to get or set the delegate that will be notified of stability, levelness and captured images.

- (kfxKUIPageDetect pageDetectMode) DEPRECATED_ATTRIBUTE
readwritenonatomicassign

Gets or sets the the page detection behavior of the control.

This property controls the page detection mode of the control.

Page detection adds an additional constraints to image capture such that an image will not be captured until a documented is detected within the viewfinder. When running, page detection will also raise events each time a page is detected if the corresponding delegate has been set. The supported modes are:

kfxKUIPageDetectOff: Turns off the page detection algorithm and its associated capture constraints.

kfxKUIPageDetectAutomatic: Enables page detection and applies the page detection constraint to image capture. Use of the algorithm is minimized to conserve resources, and events will not be generated until other capture constraints are satisfied. Usually, only a single event will be raised at the time an image is captured.

kfxKUIPageDetectContinuous: Enables page detection and runs it continuously in the background while the control is active. The page detection constraint is applied to image capture. The control will provide events releated to page detection as they become available.

When deciding to enable any of the page detection modes, consider the impacts on processing resources and battery life. The continuous mode provides more flexibility to the developer than the automatic mode, but will consume more resources as well.

Using any mode other than PageDetectMode::OFF while also using kfxKUICheckCaptureExperience or kfxKUIDocumentCaptureExperience may crash the device. The CheckCaptureExperience or DocumentCaptureExperience will automatically turn the effective mode to OFF. It is the developer's responsibility not to enable PageDetection while also using the CheckDetector or DocumentDetector.

- (int pageAreaForDetection) DEPRECATED_ATTRIBUTE
readwritenonatomicassign

The minimum area that a page must cover before it is detected as a page.

This property is a percent value. The valid range is [0 - 100]. Any values outside this range will be interpreted as the closest valid value (0 or 100). The default value is 20, which requires a page to cover at least 20% of the preview area.

When page detection is enabled, this property specifies the minimum area of the preview that a page must cover before it is considered a vaild page. Pages detected with a percent area smaller than this threhsold will not be considered valid, and will not raise any page detect events.

Very small values for this property are not advisable, and may result in small highlights and other noise being detected as pages.

Because page detection requires some margin around a page to properly detect it, the useful upper limit of this property is less than 100. Capture may be difficult when choosing values larger than 70%. Values above 90% are almost always expected to fail.

See also
pageDetectMode
- (int) deviceDeclinationPitch
readwritenonatomicassign

The reference pitch that indicates what angle means that the device is level.

A property to get or set an angle in degrees that will be used to determine that the device is level. The default value is 0, which indicates that the top and bottom of the device are in the same horizontal plane. A positive value indicates that the top of the device should be higher than the bottom for the device to be considered level, and a negative value means that the bottom should be higher.

Valid values are in the range [-180, 180].

- (int) deviceDeclinationRoll
readwritenonatomicassign

The reference roll that indicates what angle means that the device is level.

A property to get or set an angle in degrees that will be used to determine that the device is level. The default value is 0, which indicates that the left and right sides of the device are in the same horizontal plane. A positive value indicates that the left side of the device should be higher than the right for the device to be considered level, and a negative value means that the right side should be higher.

Valid values are in the range [-180, 180].

- (kfxKUIFlashSetting) flash
readwritenonatomicassign

The current camera flash mode.

A property to get or set the flash mode, with five values: kfxKUIFlashOn, kfxKUIFlashOff, kfxKUIFlashAuto, kfxKUITorch, and kfxKUITorchAuto.

- (CGPoint) focusPoint
readwritenonatomicassign

The camera focus point.

Specifies the point where the camera should adjust focus. The camera will analyze the image data in a small area around the focus point to determine the optimal focus.

The camera focus point is specified in the control's local coordinate space. The valid coordinate range is (0, 0) to (width, height) using the dimensions of the ImageCaptureControl. The property will translate these coordinates into the camera's coordinate space.

If a coordinate is specified outside an area covered by the camera preview, then the closest valid point will be used instead. For example, if the camera preview aspect ratio does not match the aspect ratio of the control, black margins will be present on sides. Specifying a point in the margin area will result in the closest point on the preview edge being used instead.

A set focus point will remain in effect until the control is invalidated. Resizing the control, changing camera parameters, or suspending the application are all sufficient to invalidate the set focus point. The value of the focus point is undefined once it is invalided.

If setting the focus point is not supported on the device, setting this property will raise an exception. Check the canSetFocusPoint property first.

See also
canSetFocusPoint
defaultFocusPoint
- (kfxKUIGPSUsageLimits) gpsUsageLimits
readwritenonatomicassign

gpsUsageLimits - controls whether GPS location information is captured with the image.

The property allows the app to determine whether the Image Capture Control includes GPS location information with the captured image. The kfxKUIGPSUsageLimits enum has two settings:

kfxKUINeverUse - GPS information will not be gathered under any circumstances. When using kfxKUINeverUse, the user is not queried for permission to collect location information. kfxKUIAlwaysUseIfEnabled - GPS information will be gathered if permitted by the operating system. With kfxKUIAlwaysUseIfEnabled, the user may be queried for permission if no user preference has previously been determined. This is the default setting of this property.

This property should be set in the viewDidLoad method (before the control is displayed).

- (kfxKUIFrame*) imageFrame
readwritenonatomicstrong

The kfxKUIFrame object.

A property to get or set the kfxKUIFrame object that puts a visual frame around the image

- (CGSize) imagePreviewSize
readnonatomicassign

Gets the camera preview resolution.

A read-only property to get the resolution of the camera preview. This value will vary depending on the target device and its camera capabilities.

Note, this property can only return an accurate value after the camera has been initialized and processed its first preview frame. This property cannot be reliably called anywhere in the view construction lifecycle, including the methods viewDidLoad and viewDidAppear.

- (int) levelThresholdPitch
readwritenonatomicassign

The threshold used to determine if the device is level.

An angle in degrees that is used when comparing the actual pitch of the device to the deviceDeclinationPitch. If the difference is less than the threshold, the device is considered level with respect to pitch. The default value is 7.

Valid values are in the range [0, 45]. Values outside this range will be interpreted as 0 or 45. A value of 45 disables level checking for pitch.

See also
deviceDeclinationPitch
- (int) levelThresholdRoll
readwritenonatomicassign

The threshold used to determine if the device is level.

An angle in degrees that is used when comparing the actual roll of the device to the deviceDeclinationRoll. If the difference is less than the threshold, the device is considered level with respect to roll. The default value is 7.

Valid values are in the range [0, 45]. Values outside this range will be interpreted as 0 or 45. A value of 45 disables level checking for roll.

See also
deviceDeclinationRoll
- (CMMotionManager*) motionManager
readwritenonatomicstrong

The motion manager being used to detect the levelness of the device.

A property to get or set the motion manager to use to detect the levelness of the device. If this is never set, one will be allocated which is available to use if the application wants to get motion events at the same time as the control. It may also be set, but that must be done in the view controller's viewDidLoad or before.

- (int) stabilityDelay
readwritenonatomicassign

The current stability delay.

A property to get or set the current stability delay. If not set, it defaults to 75.

It is a number from 0 to 100, where 100 indicates that the device must be near perfectly still to take a picture and 0 indicates that stability checking is turned off.

- (BOOL) useVideoFrame
readwritenonatomicassign

Whether the video frame is retured, or a full-resolution image is captured.

A boolean that indicates whether the video frame, or a full-resolution image is returned when capture is requested. Using the video frame may speed up image classification, but will result in less accurate results, as there is less image data to work with.

switching between video frame and full-resolution capture will cause the session preset (the capture resolution) to be reset to its default value. For video frame capture, the default preset is 1080p if supported, or 720p. For full-resoluton capture, the default preset is photo quality. If you want to change the session preset, do so after changing this property.


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