This package allows you to integrate complex python fingerprint enhancement directly into your Node.js pipelines effortlessly, or process images from your terminal using the built-in CLI.

Requirements

Since the core enhancement engine is written in Python, you must have Python installed and available in your environment, along with the following packages:

pip install numpy opencv-python scipy

Installation

Install locally inside your Node.js project:

npm install finhance

Or run directly via npx (make sure dependencies are installed!):

npx finhance <input_path>

CLI Usage

The executable takes a file, directory, or .zip archive as input.

Supported image formats: .jpg, .jpeg, .png, .bmp, .dib, .tif, .tiff

On launch the CLI prints a full-colour banner with version, author, engine and runtime info, followed by timestamped log entries for every phase of processing.

    ╔═══════════════════════════════════════════════════════╗
    ║   ███████╗██╗███╗   ██╗██╗  ██╗ █████╗ ███╗   ██╗    ║
    ║   █████╗  ██║██╔██╗ ██║███████║███████║██╔██╗ ██║    ║
    ║   ...                                                 ║
    ╚═══════════════════════════════════════════════════════╝

  Version  : v1.3.0      Author : Naseem Ansari
  Engine   : Gabor Filter (Python/OpenCV)

  ▶ Input Validation
  [INFO]  2026-05-26 12:50:00  Input type : Single file
  [INFO]  2026-05-26 12:50:00  File       : fingerprint.dib
  [  OK ]  2026-05-26 12:50:00  Input validated

  ▶ Processing
  [PROC]  █████████████████████████ 100%  [1/1]  fingerprint.dib

  ▶ Summary
    Total       : 1 image(s)
    Succeeded   : 1
    Elapsed     : 5.42s

Examples

# Enhance a single image (including .dib format)
npx finhance ./fingerprint.dib --output ./results

# Recursively enhance a folder of images
npx finhance ./dataset --recursive

# Process an entire ZIP file automatically
npx finhance ./dataset.zip --format jpg

# Only flip images horizontally (no enhancement)
npx finhance ./dataset --flip-only

# Enhance AND flip images
npx finhance ./dataset --flip

# Upscale and enhance to 4k resolution
npx finhance ./image.jpg --res 4k

Options

• --output, -o: Target output folder (Defaults to <input_dir>/finhance_output)
• --recursive, -r: Recursively search subdirectories for images
• --format, -f: Output image format (png or jpg)
• --flip-only: Bypass enhancement and just flip the images horizontally
• --flip: Applies enhancement AND flipping
• --res: Enhance image resolution (1080p, 2k, 4k) to fix blur
• --keep-temp: Prevent the system from cleaning up the temporary zip extraction folder

CLI Logging

The CLI provides production-grade, colour-coded output inspired by professional security and analysis tools:

| Tag | Meaning | |-----|---------| | [INFO] | Informational messages (input details, config echo) | | [ OK ] | Step completed successfully | | [WARN] | Non-fatal warnings (unknown flags, etc.) | | [FAIL] | Errors and failures | | [PROC] | Per-image progress with inline progress bar |

Every log line is prefixed with an ISO timestamp for traceability.

API Usage

You can seamlessly integrate finhance into your Node.js code using async/await.

const { enhance } = require('finhance');

async function processFingerprints() {
    try {
        const results = await enhance('./fingerprints.zip', {
            outputDir: './enhanced-output',
            recursive: true,
            format: 'png',
            flip: true, // enhances and flips
            res: '1080p' // upscale to 1080p
        });

        const successes = results.filter(r => r.status === 'success');
        console.log(`Processed ${successes.length} images!`);
    } catch (e) {
        console.error("Execution failed:", e.message);
    }
}

processFingerprints();

enhance(inputPath, [options])

Returns: Promise<Array> - An array of objects detailing the operation status (success or error) and output locations.

Options Object

• outputDir (string) - Absolute or relative path to output directory
• recursive (boolean) - Set to true to traverse subfolders (default: false)
• format (string) - "png" or "jpg" (default: "png")
• cleanup (boolean) - Set to false to keep temp expanded zip files (default: true)
• flipOnly (boolean) - Set to true to ONLY flip images, ignoring enhancement.
• flip (boolean) - Set to true to perform both enhancement and flipping.
• res (string) - Target resolution for upscaling (e.g., '1080p', '2k', '4k').

Credits & Attribution

This npm package acts as an orchestrator wrapper around the excellent Python structural logic created by Utkarsh-Deshmukh.

The underlying Python source code is licensed under the BSD 2-Clause License. See THIRD_PARTY_LICENSES.md for the full license text.