ImagePreview request

The SDK supports displaying a preview image by using the ImagePreview request. This request offers the following functionality:

Retrieving a default symbolic image in case no image has been captured yet. This is the request's basic use case.
Using a custom default symbolic image instead of the SDK's one as extended use case.
Creating the preview image from a current existing person's image as further option of the extended use case. This functionality also comprises the optional conversion from the source image format to an other format (for example, JPEG-2000 to JPEG). The image may also be scaled. Such a source image can be specified by an URL, a file or the BASE64 encoded image.

ImagePreview is used together with the ImageCapture request. The basic usage is the following:

Use ImagePreview to create an image preview object.
Use ImageCapture to capture a new image. The XML preview element in this request uses the same content as used with the ImagePreview request. After a successful capturing process, the new preview image is generated from the captured one. Note that ImageCapture will never create a preview image other than for the captured image: In case of canceling the capture process, the former preview image remains unchanged.

Use case

A typical use case is the usage within an HTML page in combination with an img tag and a preview image generated by the web service. The great advantage is that using a preview image created and updated by ImagePreview and ImageCapture will delegate the differentiation whether an image was captured or not to the SDK. This is very helpful in the HTML use case where it may be difficult to implement such a preview logic.

In a similar way, you may also use a fix file reference in a Windows application which binds an image preview control in a dialog to a (temporary) image file.

The extended usage of PreviewImage allows image preview creation from custom default symbolic images and/or an existing person's image. This is supported by specifying one or two default image sources. Each of these image sources may be a file reference, an URL or a BASE64 encoded image.

The basic use case, without providing own default images is the following:

If an image was captured, this is the one that is returned as preview image.
If no image was captured, the SDK's symbolic image is returned.

The extended use case, providing own default images can be illustrated in this way:

Note that without providing default images, the sequence falls back automatically to the basic use case.

Request and Response overview

Request (REST)

POST http://localhost:54880/ImagePreview

Request (SOAP)

soap operation ImagePreview

Request Data

<?xml version="1.0"?>
	<image type="photo" format="jpg">
	<preview image="photo.jpg" data=""
		max_width="100" max_height="100"/>
</image>

Response Data on success

<?xml version="1.0"?>
<image type="photo" format="jpg">
	<preview image="photo.jpg" data="7CD8427...6313"
		max_width="100" max_height="100"/>
</image>

Response Data on error or cancel, see Introduction to API.

Request and Response in detail

The used XML is nearly the same as for the ImageCapture request. It does not contain the result element but only the preview element which contains the attributes default_image_1 and default_image_2 in addition.

Element	Attribute	Description
`image` [in], Required. Root element for the preview request	`type`	[in], Required. Image object type to be captured: photo, signature, fingerprint or document. The type indicates the kind of symbolic image which is returned if no image is captured.
	`format`	[in], Required. Image format of the returned image: jpg, bmp, tif or jp2.
`image/preview` [in] Required. Element that describes the way the captured image is returned. It contains all attributes as described for the `ImageCapture` request and the following attributes `default_image_1` and `default_image_2` in addition.	`default_image_1`	[in] The first default image to be returned if no image is captured. It may be An URL to a image object. For example: http://myserver/images/image10032.jpg or http://myserver/imgservlet?joanne_doe.jpg. A file reference. For example c:/images/joanne_doe.jpg BASE64 encoded image data (in jpg, bmp, tif or jp2 format).
	`default_image_2`	[in] The second default image to be returned if no image is captured. Same values are allowed as described for `default_image_1`.