Capturing an image is done using the ImageCapture request. The request shows the capture dialog and requires some user interaction depending on the device. It is processed synchronously: When the user confirms or cancels the capture process the dialog will close and the request will return. The captured image may be returned in different ways: As BASE64 encoded image data and as file. Furthermore, it may be returned as additional thumbnail image, again BASE64 encoded and as file but in addition as temporarily persistent web service object. This image object can be retrieved via HTTP GET requests from the web service.

Request and Response overview

Request (REST)

POST http://localhost:54880/ImageCapture

Request (SOAP)

soap operation ImageCapture

Request Data

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

Response Data on success

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

Request and Response in detail

Element	Attribute	Description

Element	Attribute	Description
`image` [in], Required. Root element for the capture request	`type`	[in], Required. Image object type to be captured: photo, signature, fingerprint or document.
	`format`	[in], Required. Image format of the captured image: jpg, bmp, tif or jp2.
	`language`	[in], Language of the user interface. For details see Introduction to API.
`image/result` [in], Required. Element that describes the way the captured image is returned.	`data`	[in,out] Request and response for BASE64 encoded image data: In the request an existing empty data attribute (data=””) instructs the component to return the image BASE64 encoded. In this case the response contains the BASE64 encoded image.
	`file`	[in] An absolute file path (for example “c:\images\001.jpg”) in MS-DOS/Microsoft Windows style, that describes where the captured image shall be stored. If the image already exists, it is overwritten.
`image/preview` [in] The element instructs the component to return the captured image as additional second image. This image may be requested to be smaller and/or in another image format. As the name indicates, it is intended to deliver a sort of thumbnail image for preview purposes. A typical use case is to capture an image in JPG 2000 format and to return a second standard JPG image for preview purposes.	`data`	[in,out] Request and response for BASE64 encoded preview image data: In the request an existing empty data attribute (data=””) instructs the component to return the preview image BASE64 encoded. In this case the response contains the BASE64 encoded preview image.
	`file`	[in] An absolute file path for example “c:\images\preview.jpg”) in MS-DOS/Microsoft Windows style that describes where the captured preview image shall be stored. If the image already exists it is overwritten.1
	`image`	[in,out] If this attribute is provided it instructs the capture component to create the image on the web service, retrievable via an HTTP GET request. In the request, you may either provide an empty value (image=””) or an name of the image object (for example, `image`=”photo15.jpg”). The response contains, if an empty value was provided, a generated unique name for the attribute's value (for example, `image`=”photo15.jpg”). If a value was provided, the attribute's value is unchanged. In both cases, the captured image is available using the URL http://localhost:54880/photo15.jpg. A typical use case is to provide a preview image within an HTML page via an HTML `img` tag. The image is retrievable as long as the service is running or until an HTTP DELETE request for this image is done (always use the complete URL like http://localhost:54880/front15.png with GET or DELETE). The web service's list is limited to 100 images. If more images are requested, the first ones created are deleted (realizing a FIFO principle).
	`format`	[in] Describes the format of the returned preview image. Values are jpg, bmp, tif or jp2. If the attribute does not exist, the file extension of the image element describes the format of the preview image.
	`max_width` `max_height`	[in] Values describing the maximal size of the returned image. The aspect ratio of the captured image is always kept. In other words: the returned image is scaled, so that it fits into a rectangle defined by these values. The value's unit is pixel.
`image/original` [in] The element instructs the component, to offer the original image as input source Original. It is then offered for the standard frame selection and image processing process.	`data`	[in] Contains the original image, BASE64 encoded. The format of the provided image is automatically recognized. Supported image formats are jpg, bmp, tif and jp2.

Example preload image stored as file

Request:

<?xml version="1.0"?>
<image type="photo" format="jpg" language="EN">
<result data="" file="C:\test.jpg"/>
<original data="...BASE64..."/> <parameters>
<ImageWidthNew>300</ImageWidthNew>
<ImageHeightNew>300</ImageHeightNew>
<UseDefinedSize>true</UseDefinedSize>
</parameters>
</image>

Response:

<?xml version="1.0"?>
<image type="photo" format="jpg" language="EN">
<result data="...BASE64.../> <parameters>
<ImageWidthNew>300</ImageWidthNew>
<ImageHeightNew>300</ImageHeightNew>
<UseDefinedSize>true</UseDefinedSize>
</parameters>
</image>

Nexus Documentation

ImageCapture request