Docscanner Project Documentation

Overview
The Docscanner project is an ActiveX control (OCX) designed for fingerprint acquisition,
processing, and matching. It serves as a comprehensive solution for biometric identification
systems, particularly those requiring fingerprint-based authentication or identification.

Purpose
The primary purpose of the Docscanner project is to provide a robust, embeddable component
that enables applications to:
1. Acquire fingerprint images from hardware scanners
2. Process these images to enhance quality and extract features
3. Compress fingerprint data using industry-standard algorithms
4. Match fingerprints against stored templates
5. Support various fingerprint-related operations in a secure and efficient manner
Scope
The scope of the Docscanner project encompasses:
1. Hardware Integration: Interfacing with TWAIN-compatible scanners to acquire
fingerprint images
2. Image Processing: Enhancing, rotating, and segmenting fingerprint images
3. Feature Extraction: Identifying and extracting minutiae points from fingerprints
4. Compression: Implementing WSQ (Wavelet Scalar Quantization) compression for
efficient storage
5. Pattern Classification: Categorizing fingerprints into standard pattern types
6. Barcode Reading: Supporting barcode recognition for document processing
7. Multilingual Support: Providing interfaces in multiple languages

Technical Architecture
Component Structure
The Docscanner project is structured as an ActiveX control with several key components:
1. Core Control Class: “CDocscannerCtrl” serves as the main interface between host
applications and the fingerprint processing functionality.

2. Image Acquisition: “CTWAINScan” handles communication with scanner hardware

through the TWAIN protocol.
 3. Image Processing: Multiple specialized classes handle different aspects of image
processing:

– “CLocatePrints” for fingerprint localization

– “CDocscannerCtrl” also provides few image processing functionalites
– “PlainPrintRotation” for fingerprint rotation
– “CPictureEx” for enhanced image display
4. Feature Extraction: Components in the cc/source directory handle minutiae extraction
and processing:

– Minutia.cpp for individual minutiae points

– Minutiae.cpp for collections of minutiae
– Relations.cpp for relationships between minutiae
5. Compression: WSQ compression functionality is provided through the interface defined
in “Wsq_dll.h” .

6. UI Thread Management: “UIThread.cpp” implements multi-threading to keep the UI

responsive during processing.

7. Barcode Reading: “BarcodeReader.cpp” provides barcode recognition capabilities.

8. Multilingual Support: “BiLingualSupport.h” enables localization of the interface.

Technology Stack
The project leverages several key technologies:
1. C++ and MFC: The core application is built using C++ with Microsoft Foundation Classes
for the UI components.

2. ActiveX: The application is packaged as an ActiveX control for easy embedding in other
applications.

3. OpenCV: Extensive use of OpenCV for image processing tasks, with support for:

– Core image processing (imgproc)

– GPU acceleration (gpu)
– OpenCL integration (ocl)
– Machine learning algorithms (ml)
– Video processing (video)
4. TWAIN: Standard protocol for communication with scanner hardware.

5. WSQ: FBI standard for fingerprint image compression.

Workflow
The typical workflow of the Docscanner component follows these steps:
1. Initialization: The ActiveX control is initialized when embedded in a host application.

2. Configuration: Scanner and processing parameters are configured through the control’s
properties.

3. Acquisition: Fingerprint images are acquired from a connected scanner.

4. Pre-processing:

– Images are converted to grayscale

– Background noise is removed
– Image quality is enhanced
– Fingerprints are located within the scanned image
5. Feature Extraction:

– Images are binarized (converted to black and white)

– Ridge patterns are thinned to single-pixel width
– Minutiae points (ridge endings and bifurcations) are identified
– Minutiae attributes (position, orientation, type) are calculated
6. Pattern Classification: Fingerprints are classified into standard pattern types (arch, loop,
whorl, etc.).

7. Compression: Processed fingerprint images are compressed using WSQ.

8. Storage/Transmission: Compressed images and extracted features are stored or

transmitted as needed.

9. Matching (if applicable): Fingerprints are compared against stored templates for
identification or verification.

Integration Points
The ActiveX control provides several integration points for host applications:
1. Methods: Functions that can be called to perform specific operations.

2. Properties: Values that can be read or set to configure the control.

3. Events: Notifications that are sent to the host application when specific conditions
occur.

This comprehensive architecture enables the Docscanner component to provide robust

fingerprint processing capabilities while maintaining flexibility for integration into various host
applications.
Component Structure Documentation: Image
Acquisition
Image Acquisition Component: Facts4TwainScanner
The Facts4TwainScanner class, defined in CTWAINScan.h and implemented in
CTWAINScan.cpp , serves as the primary interface for fingerprint image acquisition in the
Docscanner project. This class inherits from CTwain , which provides the core TWAIN protocol
implementation.

TWAIN Protocol Overview

TWAIN (Technology Without An Interesting Name) is an industry-standard protocol that
enables communication between software applications and image acquisition devices such as
scanners. The protocol follows a state-based model with well-defined transitions between
states, allowing for controlled image acquisition.

Facts4TwainScanner Architecture
The Facts4TwainScanner class encapsulates all scanner-related functionality, providing a high-
level interface for:
1. Scanner Connection Management :

– Opening and closing connections to scanner devices

– Managing the TWAIN session state
– Handling scanner availability
2. Scanner Configuration :

– Setting scanning parameters such as resolution, brightness, and contrast

– Configuring the scanning window (area to be scanned)
– Setting bits per pixel and scaling factors
3. Image Acquisition :

– Initiating the scanning process

– Receiving scanned image data
– Converting device-specific formats to application-usable formats
4. Error Handling :

– Detecting scanner availability issues

– Handling exceptions during the scanning process
– Providing error information to the application
Key Methods and Their Functionality Initialization and Cleanup
• Facts4TwainScanner::Facts4TwainScanner : Initializes the scanner interface with a
window handle for UI operations

• Facts4TwainScanner::~Facts4TwainScanner : Cleans up resources, particularly the DIB

(Device Independent Bitmap) handle Scanner Connection Management

• Facts4TwainScanner::Open : Opens a connection to the scanner device, registering the

application with the TWAIN source manager

• Facts4TwainScanner::Close : Closes the connection to the scanner and the TWAIN

source manager

• Facts4TwainScanner::IsScannerAvailable : Checks if the scanner is available for use

Scanner Configuration

• Facts4TwainScanner::SetBrightness : Sets the brightness level for scanning

• Facts4TwainScanner::SetSharpness : Sets the contrast/sharpness level for scanning

• Facts4TwainScanner::SetRes : Sets the horizontal and vertical resolution in dots per inch

• Facts4TwainScanner::SetWindow : Defines the area to be scanned (in inches)

• Facts4TwainScanner::SetBitsPerPixels : Sets the color depth for scanning

• Facts4TwainScanner::SetScalingFactor : Sets the scaling factor for the scanned image

Image Acquisition

• Facts4TwainScanner::Scan : Initiates the scanning process, optionally showing the

scanner’s UI

• Facts4TwainScanner::DibReceived : Callback method that receives the scanned image

data as a DIB handle Information Retrieval

• Facts4TwainScanner::GetNumberOfRows : Gets the height of the scanned image in

pixels

• Facts4TwainScanner::GetNumberOfColumns : Gets the width of the scanned image in

pixels
 • Facts4TwainScanner::GetOutputResolution : Retrieves the actual resolution of the
scanned image

• Facts4TwainScanner::GetCapability : Retrieves capability information from the scanner

Integration with the Image Processing Pipeline
The Facts4TwainScanner class integrates with the image processing pipeline through the Image
template class. When an image is scanned, the data is received as a DIB handle in the
Facts4TwainScanner::DibReceived method. This method:
1. Checks if the image is 8-bit grayscale (required for fingerprint processing)
2. Stores the resolution information for later use
3. Shares the DIB handle with the Image object using the ShareDib method
4. Throws an exception if the image format is not compatible
Error Handling
The Facts4TwainScanner class includes robust error handling:
1. It maintains a m_bScannerAvailable flag to track scanner availability
2. It throws Facts4TwainScannerException objects when errors occur
3. It provides detailed error information through the TWAIN condition codes
Memory Management
The class implements reference counting through the Facts4TwainScanner::DuplicatePointer
and Facts4TwainScanner::DestroyPointer methods, allowing for safe sharing of scanner objects
across different parts of the application.

Underlying TWAIN Implementation

The Facts4TwainScanner class relies on the CTwain base class for the core TWAIN protocol
implementation. This base class:
1. Manages the TWAIN state machine

2. Handles message processing for TWAIN events

3. Provides low-level access to TWAIN capabilities

4. Implements the data transfer mechanisms The TWAIN protocol follows a state-based
model with the following states:

5. PRE_SESSION

6. SOURCE_MANAGER_LOADED

7. SOURCE_MANAGER_OPEN
 8. SOURCE_OPEN

9. SOURCE_ENABLED

10. TRANSFER_READY

11. TRANSFERRING

The Facts4TwainScanner class abstracts these states, providing a simpler interface for the
application while ensuring proper state transitions according to the TWAIN specification.

Component Structure Documentation: Core Control

Interface
Core Control Interface: CDocscannerCtrl
The CDocscannerCtrl class, defined in DocscannerCtrl.h and implemented in DocscannerCtrl.cpp
, serves as the central component of the Docscanner ActiveX control. This class inherits from
COleControl and provides the primary interface between host applications and the fingerprint
processing functionality.

Architecture Overview
The CDocscannerCtrl class implements the ActiveX control interface defined in Docscanner.idl ,
exposing methods and properties that can be accessed by host applications. The control is
registered with the system through the CDocscannerCtrlFactory::UpdateRegistry method,
which adds the necessary registry entries for COM integration.
The control’s unique identifiers are defined in Docscanner_i.c , including:
• Library ID (LIBID_DocscannerLib): B56E4061-DF7C-4FCD-A3CD-37D6643A4D1D
• Interface ID (DIID__DDocscanner): B28EBB45-86C9-4D96-B837-E9B4A0F319EE
• Events Interface ID (DIID__DDocscannerEvents): 9DFC54D3-1392-4FE4-99A3-
9E55921400D8
• Class ID (CLSID_Docscanner): 6AA1BD16-C335-4A60-A6EE-2EFC195EAE07
Core Functionality
The CDocscannerCtrl class provides comprehensive functionality for fingerprint acquisition,
processing, and feature extraction:
1. Scanner Configuration
The control allows host applications to configure scanner parameters through
the following methods:
• CDocscannerCtrl::SetWindow : Defines the scanning area in inches (X, Y, width,
height)
 • CDocscannerCtrl::SetBrightness : Sets the brightness level for scanning

• CDocscannerCtrl::SetContrast : Sets the contrast/sharpness level for scanning

• CDocscannerCtrl::SetRes : Sets the horizontal and vertical resolution in dots per inch

• CDocscannerCtrl::SetIEVersion : Sets the Internet Explorer version for compatibility

2. Image Acquisition

The control provides methods for acquiring fingerprint images:

• CDocscannerCtrl::OpenScanner : Opens the scanner without showing the UI

• CDocscannerCtrl::OpenScannerWithUI : Opens the scanner and shows the scanner’s

UI

• CDocscannerCtrl::GetBufferHttp : Scans an image and sends it to a server via HTTP

3. Fingerprint Processing

The control includes methods for processing fingerprint images:

• CDocscannerCtrl::GetLocatePrints : Locates and extracts individual fingerprints from

a scanned image

• CDocscannerCtrl::GetChancePrintImages : Extracts chance prints (latent

fingerprints) from a scanned image

• CDocscannerCtrl::GetEnhancedImage : Enhances a fingerprint image using various

algorithms

4. Feature Extraction

The control provides methods for extracting features from fingerprint images:

• CDocscannerCtrl::GetPrintFeatureXML : Extracts fingerprint features and returns

them as XML

• CDocscannerCtrl::EncodeChancePrints : Encodes chance prints and sends them to a

server

• CDocscannerCtrl::EncodeRolledandPlainPrints : Encodes rolled and plain prints and

sends them to a server

5. Image Compression and Conversion

The control includes methods for compressing and converting fingerprint images:
 • CDocscannerCtrl::GetJpegBuffer : Compresses a fingerprint image using JPEG and
returns it as a base64-encoded string

• CDocscannerCtrl::GetChanceprintJpegImages : Returns a chance print as a JPEG

image

• CDocscannerCtrl::GetChanceprintPNGImages : Returns a chance print as a PNG

image

6. Barcode Reading

The control includes a method for reading barcodes from scanned images:

• CDocscannerCtrl::GetBarcodeString : Reads a barcode from a specified region of the

scanned image

Data Management
The CDocscannerCtrl class manages several types of data:
1. Scanner Configuration Data
The class maintains member variables for scanner configuration:
• m_StartX , m_Starty , m_Width , m_Height : Define the scanning area

• m_Sharpness , m_Brightness : Control image quality

• m_Xres , m_Yres : Define scanning resolution

• m_bitsPerPixel : Defines the color depth for scanning

2. Image Data

The class manages several types of image data:

• ScannedBuffer : Stores the raw scanned image

• ScannedImages[NUMBER_OF_PRINTS] : Stores individual fingerprint images

• ChancePrintImages[NUMBER_OF_PRINTS] : Stores chance print images

• ImagestoEncode[NUMBER_OF_PRINTS] : Stores images prepared for encoding

• PlainImgBuffer[NUMBEROFFINGERS] : Stores plain fingerprint images

• Mnt_Rolled[NUMBEROFFINGERS] : Stores minutiae data for rolled fingerprints

3. Processing Parameters

The class maintains parameters for fingerprint processing:

 • MaxNumberOfEnhancements : Controls the number of enhancement iterations

• Print_mode : Defines the type of print being processed

• SkelCompFlag : Controls whether skeleton compression is used

• MatchingScore : Sets the threshold for fingerprint matching

• JuvenileStatus and JuvenileScaleFactor : Handle juvenile fingerprints

Integration with External Libraries

The CDocscannerCtrl class integrates with several external libraries:
1. TWAIN Interface
The control uses the TWAIN interface for scanner communication, as implemented
in CTWAINScan.cpp

2. Image Processing Libraries

The control uses several image processing libraries:
• OpenCV for general image processing

• FreeImage for image format conversion

• Custom libraries for fingerprint-specific processing

3. Compression Libraries

The control uses several compression libraries:

• JPEG compression through jpegb_encode_mem

• WSQ compression through wsq_encode_mem

• PNG compression through lodepng_encode_memory

4. Feature Extraction Libraries

The control uses custom libraries for fingerprint feature extraction:

• EncodePrint for extracting minutiae

• segment_fingers for segmenting fingerprints

• parse_segfing for parsing segmented fingerprints

Memory Management
The CDocscannerCtrl class implements careful memory management:
1. Allocation : The class allocates memory for various image buffers as needed
2. Deallocation : The destructor frees all allocated memory
3. Reference Counting : The class uses reference counting for shared resources
4. Error Handling : The class checks for memory allocation failures and reports errors
Error Handling
The control implements robust error handling:
1. Error Codes : The class defines error codes for common failure scenarios
2. Logging : The class includes logging functionality through the WriteTimetoFile and
WriteLogtoFile methods
3. Exception Handling : The class catches and handles exceptions during processing
Property Page Support
The control includes a property page for configuration through the CDocscannerPropPage class.
This class:
1. Inherits from COlePropertyPage
2. Provides a dialog-based interface for configuring the control
3. Handles data exchange between the dialog and the control’s properties
Application Module
The CDocscannerApp class, defined in Docscanner.h and implemented in Docscanner.cpp ,
serves as the DLL’s application module. This class:
1. Inherits from COleControlModule
2. Initializes and terminates the DLL
3. Provides registration and unregistration functionality through DllRegisterServer and
DllUnregisterServer
Multi-threading Support
The control includes multi-threading support through the CUIThread class. This allows the
control to:
1. Perform CPU-intensive operations in a background thread
2. Keep the UI responsive during processing
3. Notify the host application when processing is complete
Key Processing Algorithms
The control implements several key algorithms for fingerprint processing:
 1. Image Enhancement
The control enhances fingerprint images using:
• Contrast adjustment

• Noise reduction

• Ridge enhancement

• Power transformation

2. Fingerprint Segmentation

The control segments fingerprints using:

• Coordinate-based extraction

• Rotation to correct orientation

• Region of interest extraction

3. Feature Extraction

The control extracts fingerprint features using:

• Minutiae detection

• Ridge pattern analysis

• Core and delta point detection

Integration Points for Host Applications

Host applications can integrate with the control through:
1. Method Calls : Calling the control’s methods to perform operations
2. Property Access : Reading and writing the control’s properties
3. Event Handling : Responding to events fired by the control This comprehensive
architecture enables the CDocscannerCtrl class to provide robust fingerprint processing
capabilities while maintaining flexibility for integration into various host applications.

Key Method Of CDocscannerCtrl

The CDocscannerCtrl class contains numerous methods that can be categorized by their
functionality. Below is a detailed explanation of key methods in each category:
Scanner Configuration Methods

• SetWindow(double StartX, double StartY, double width, double height): Defines the
scanning area in inches. The parameters specify the top-left corner (StartX, StartY) and
the dimensions (width, height) of the area to be scanned. This method calls the
underlying TWAIN interface’s setWindow function.

• SetBrightness(long Brightness): Sets the brightness level for scanning. The parameter
ranges typically from 0 to 255, with higher values producing brighter images. This
method calls the underlying TWAIN interface’s setBrightNess function.

• SetContrast(long contrast): Sets the contrast/sharpness level for scanning. The

parameter ranges typically from 0 to 255, with higher values producing higher contrast.
This method calls the underlying TWAIN interface’s setContrast function.

• SetRes(long Xres, long Yres): Sets the horizontal and vertical resolution in dots per inch.
Higher resolution values produce more detailed images but require more memory. This
method calls the underlying TWAIN interface’s setResolution function.

• SetIEVersion(short majorIEVersion): Sets the Internet Explorer version for compatibility

with the TWAIN interface. This is necessary because different versions of IE may interact
differently with the TWAIN interface.

Image Acquisition Methods

• OpenScanner(): Opens a connection to the scanner without showing the scanner’s UI.
Returns TRUE if successful, FALSE otherwise.

• OpenScannerWithUI(): Opens a connection to the scanner and shows the scanner’s UI,
allowing the user to configure scanner settings. Returns TRUE if successful, FALSE
otherwise.

• GetBufferHttp(LPCTSTR ServerIP, LPCTSTR Resource, LPCTSTR AppTxnId, short

PortNo): Scans an image and sends it directly to a server via HTTP. The parameters
specify the server IP, resource path, application transaction ID, and port number.

• GetJpegBuffer(): Compresses the scanned image using JPEG compression and returns it
as a base64-encoded string. This method is useful for web applications that need to
display the scanned image.

Fingerprint Processing Methods

• GetLocatePrints(LPCTSTR Coordinates, LPCTSTR printOrientation, short

SequenceValidationFlag): Locates and extracts individual fingerprints from a scanned
 image based on the specified coordinates and orientation. The coordinates parameter
contains the coordinates of the fingerprint regions, and the printOrientation parameter
contains the rotation angles for each fingerprint.

• GetChancePrintImages(LPCTSTR LocateCoordinates): Extracts chance prints (latent

fingerprints) from a scanned image based on the specified coordinates.

• GetEnhancedImage(short DigitNo, LPCTSTR EnhancementType, LPCTSTR

RegionOfInterest, short saveImageFlag): Enhances a fingerprint image using various
algorithms. The parameters specify the finger number, enhancement type, region of
interest, and whether to save the enhanced image.

Feature Extraction Methods

• GetPrintFeatureXML(short DigitNo, short mode): Extracts fingerprint features from the

specified finger and returns them as XML. The parameters specify the finger number
and the extraction mode (rolled or plain).

• EncodeChancePrints(LPCTSTR ServerIP, LPCTSTR Resource, LPCTSTR AppTxnId, short

PortNo, short DigitNo, short CompressionType): Encodes chance prints and sends them
to a server. The parameters specify the server details, finger number, and compression
type.

• EncodeRolledandPlainPrints(LPCTSTR ServerIP, LPCTSTR Resource, LPCTSTR AppTxnId,

short PortNo, LPCTSTR Coordinates, LPCTSTR RolledPrintAngles, LPCTSTR
PlainPrintAngles, short SeqValidationFlag): Encodes rolled and plain prints and sends
them to a server. The parameters specify the server details, coordinates, print angles,
and sequence validation flag.

Image Compression and Conversion Methods

• GetJpegBuffer(): Compresses a fingerprint image using JPEG and returns it as a base64-

encoded string.

• GetChanceprintJpegImages(short DigitNo): Returns a chance print as a JPEG image. The

parameter specifies the finger number.

• GetChanceprintPNGImages(short DigitNo): Returns a chance print as a PNG image. The

parameter specifies the finger number.
Barcode Reading Methods

• GetBarcodeString(LPCTSTR Coordinates): Reads a barcode from a specified region of

the scanned image. The parameter specifies the coordinates of the barcode region.

Configuration and Status Methods

• SetMaxNumberOfEnhancements(short MaxNumEnh): Sets the maximum number of

enhancement iterations to be performed on fingerprint images.

• GetMaxNumberOfEnhancements(): Returns the current maximum number of

enhancement iterations.

• SetPrintMode(short print_type): Sets the type of print being processed (rolled, plain, or
chance).

• SetSkeletonCompFlag(short SkelComp): Controls whether skeleton compression is used

during feature extraction.

• SetMatchingScore(short matchingThreshold): Sets the threshold for fingerprint

matching.

• GetVersionInfo(): Returns version information for the control.

Memory Management Methods

• FreeActiveXMemory(): Frees all memory allocated by the control, including image

buffers and feature data.

Logging and Debugging Methods

• EnableLogDetails(short logDetailsFlag): Enables or disables detailed logging. When

enabled, the control writes detailed information about its operations to a log file.

• WriteTimetoFile(CString strMessage): Writes a timestamped message to the log file.

• WriteLogtoFile(CString strMessage): Writes a message to the log file.

• WriteDurationToFile(clock_t start, clock_t finish, CString strMessage): Writes the

duration of an operation to the log file.
Juvenile Processing Methods

• SetJuvenileStatus(short JuvenileFlag): Sets whether the fingerprints being processed

are from a juvenile.

• SetJuvenileFactor(short JuvenileFlag, float ScaleFactor): Sets the juvenile status and

scaling factor for processing juvenile fingerprints.

• GetJunvinileprintJpegImages(LPCTSTR Coordinates): Returns juvenile fingerprint

images as JPEG images.

Utility Methods

• GetNumberofRows(): Returns the number of rows (height) of the scanned image.

• GetNumberofColumns(): Returns the number of columns (width) of the scanned image.

• GetImageDepth(): Returns the color depth (bits per pixel) of the scanned image.

• GetImageResolution(): Returns the resolution (DPI) of the scanned image.

• GetWindowsDir(): Returns the Windows directory path.

• getScannerName(): Returns the name of the connected scanner.

This comprehensive set of methods enables the CDocscannerCtrl class to provide robust
fingerprint processing capabilities while maintaining flexibility for integration into various host
applications.