ImageCapture request
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
<?xml version="1.0"?>
<image type="photo" format="jpg">
<result data="2AD352...//623=="/>
<preview data="7CD823...188313=="
image="photo15.jpg" max_width="200" max_height="200"/>
<image>
Response Data on error or cancel, see Introduction to API.
Request and Response in detail
Element | Attribute | Description |
---|---|---|
[in], Required. Root element for the capture request |
| [in], Required. Image object type to be captured: photo, signature, fingerprint or document. |
| [in], Required. Image format of the captured image: jpg, bmp, tif or jp2. | |
| [in], Language of the user interface. For details see Introduction to API. | |
[in], Required. Element that describes the way the captured image is returned. |
| [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. |
| [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. | |
[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. |
| [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. |
| [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 | |
| [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, | |
| [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. | |
| [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. | |
[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. |
| [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>