Execute (ImageKit Control/ Scan Method)

This method retrieves an image from a TWAIN datasource (scan device).

Parameters

Return Value

Returns True when successful, returns False when not successful.

Explanation

The Execute method retrieves an image from a TWAIN datasource (scan device). Events are generated before, during, and after the scan (BeforeScan, AfterScan, and Scanning events) so it is possible to write processing code in each of these stages of the scan process.

The Index parameter is enabled only when the UiMode property is vikScanNONUI and the ScanMode property is vikScanCAMArray or vikScanCAMThumbArray (set for a digital camera).

For example, to retrieve the 5th and 8th image from a digital camera, set the Index array parameter to

   Index[0] := 5;

   Index[1] := 8;

Prior to executing the Execute method, you must execute the Initialize method.

If the OpenDataSource method is executed prior to the Execute method, then while the scan device is open, other applications can not use that scan device and it becomes the exclusive datasource for this execution.

The Execute method corresponds to the Scan Control's ScanExec method in earlier versions of the ImageKit. 

<The following properties should be set prior to executing the Exeutec method>

[Required properties]

DataSourceName - if this property is blank, then select the scan device by executing the Select method.
Note: If the OpenDataSource method is executed prior to executing the DsName method then the DataSourceName is disabled and the open scan device is used.
TransferMode
Compression
UiMode
ExtUiMode) - This property is required only when using Epson scanner drivers.

[These properties may be required depending on the settings]

FileFormat
FileName
InformationFileName
JpegQuality

 

When UiMode is vikScanNONUI and ScanMode is vikInformationFile:
ScanMode, PageCount, UnitMode

When UiMode is 2 (ikScanNONUI) and ScanMode is other than vikInformationFile:

When using a scanner, it is recommended that the following properties be set when the UiMode property is 2:
AdjustGamma, AutoBright, BitDepth, BitDepthReduction, Border, BorderColor, BorderDetection, Brightness, ColorBWRatio, Contrast, Deskew , DropoutColor, DynamicThreshold, FocusPosition, Gamma, HalfTone, Highlight, IgnoreBackColor, ImageFilter, ImageMerge, Indicator, MoireFilter, NoiseFilter, Orientation, OverScan, PageCount, PaperSize, PixelType, RemoveHole, Rotation, ScanMode, ScanningSpeed, Shadow, Sharpness, SkipBlankPage, SkipBlankThreshold, TextEnhancement, Threshold, UnitFlag, UnitMode, XResolution, XScaling, YResolution, YScaling, PaperSize<=0: RectBottom , RectLeft, RectRight, RectTop

Note: The AdjustGamma, Border, BorderColor, ColorBWRatio, DynamicThreshold, FocusPosition, IgnoreBackColor, MoireFilter, RemoveHole, RotateBack, ScanningSpeed, Sharpness, SkipBlankThreshold, TextEnhancement properties are sometimes disabled depending on the scan driver.

When using a digital camera, it is recommended that these properties be set when the UiMode property is 2:
PageCount, ScanMode, UnitMode

Note: If the ScanMode property is 1, then the XResolution should be set to 0.

<The following properties are set after the scan has executed>

BitDepth, Compression, ErrorStatus, FileFormat (when using file transfer method), PixelType, RectBottom, RectLeft, RectRight, RectTop, ScanCount, UnitMode, XResolution, YResolution

For details, please refer to the respective properties' explanations.

Important points when using a custom built user interface (UiMode = 2)

When UiMode is 2, depending on the scan device and the property values set, the scan can fail. For the most part the causes for scan failure when the UiMode is 2 can be traced to the following:

The scan units set are not supported by the scan device. The supported scan unit values can be retrieved using the GetCapEnumToFloat method.
The pixel type set is not supported by the scan device. The supported pixel type values can be retrieved using the GetCapEnumToFloat method.
The bit count set is not supported by the scan device. The supported bit count values can be retrieved using the GetBitDepth method.
The resolution set is not supported by the scan device. The supported resolution values can be retrieved using the GetCapEnumToFloat or the GetCapRange methods.
The paper size set is not supported by the scan device. The supported values can be retrieved using the GetCapEnumToFloat method.

If settings for paper size are not supported at all, then set the PaperSize property to 0 and set the appropriate scan area in the RectLeft, RectTop, RectRight, and RectBottom properties. If the scan area is not correctly set (i.e. it is smaller than the minimum or larger than the maximum), the scan can fail. The proper scan area values can be retrieved using the GetMinimumSize and GetPhysicalSize methods.
If paper size settings are supported and the scan still fails, check to make sure the PaperSize property is set to a value other than 0.

Sample Code:

In Delphi

var
   Ret: Boolean;
begin
   Ret := VImageKit1.Scan.Initialize(1, 0, '1.00', 'NEWTONE Corp. ', 'ImageKit', 'ImageKit Scan Sample');
   if Ret = False Then Exit;

   VImageKit1.Scan.ClearProperty;
   VImageKit1.Scan.TransferMode := vikScanMemory;
   VImageKit1.Scan.Compression := vikScanNoCompress;
   VImageKit1.Scan.UiMode := vikScanUI;
   VImageKit1.Scan.DataSourceName := 'EPSON TWAIN Pro';
   Ret := VImageKit1.Scan.Execute;

   Ret := VImageKit1.Scan.Terminate;
end;

//Event
{$IFDEF CONDITIONALEXPRESSIONS}
   {$IF CompilerVersion >= 23.0}
procedure TForm1.VImageKit1AfterScan(Sender: TObject; DibHandle,
   OrgHandle: NativeUInt; ImageCount: Integer; BitOrder: Smallint);
   {$ELSE}
procedure TForm1.VImageKit1AfterScan(Sender: TObject; DibHandle,
   OrgHandle: Cardinal; ImageCount: Integer; BitOrder: Smallint);
   {$IFEND}
{$ENDIF}
begin
   VImageKit1.DisplayMode := vikScale
   VImageKit1.ImageHandle := VImageKit1.CopyImage(DibHandle);
end;

Differences between the ImageKit7/8/9/10

The name of this method has been changed from Exec
The Const parameter has been added to the Index
In C++Builder, the Index_Size parameter has been added
When the ScanMode property is vikScanCAMArray or vikScanCAMThumbArray, it is no longer necessary to set the number of elements in the array in the PageCount property. However, in C++Builder, the number of elements needs to be passed into the Index_Size parameter.