bkguard-lib

BKGuard is a image moderation library. It provides perceptual image hashing (dHash and pHash), keypoint-based image verification (ORB), and metric space lookup indexing via BK-Trees.

Documentation

For a detailed breakdown of all public classes, methods, and configurations, see the API Reference.

Quick Example

Here is an example of loading a banned template image, extracting its perceptual hashes and ORB features, registering them in the stores/policy, and checking an incoming filtered image:

import * as fs from "node:fs/promises";
import { 
  DHasher, 
  PHasher, 
  BannedHashStore, 
  ModerationPolicy, 
  SharpImageDecoder, 
  orb_extract 
} from "bkguard-lib";

// 1. Initialize core utilities
const dHasher = new DHasher();
const pHasher = new PHasher();
const decoder = new SharpImageDecoder();

// 2. Generate signatures (hashes and ORB features) for your banned template image
const bannedBuffer = await fs.readFile("./banned-template.png");
const bannedBytes = new Uint8Array(bannedBuffer);

const dRaster = await decoder.decodeGrayscale(bannedBytes, 9, 8);
const pRaster = await decoder.decodeGrayscale(bannedBytes, 32, 32);

const targetDHash = dHasher.hash(dRaster);
const targetPHash = pHasher.hash(pRaster);
const targetORB = await orb_extract(bannedBytes);

// 3. Initialize the stores with the generated banned hashes
const bannedDHashStore = new BannedHashStore([targetDHash], { threshold: 6 });
const bannedPHashStore = new BannedHashStore([targetPHash], { threshold: 6 });

// 4. Create a moderation policy, including ORB features for rotational/cropping verification
const policy = new ModerationPolicy(
  dHasher,
  pHasher,
  decoder,
  bannedDHashStore,
  bannedPHashStore,
  [
    {
      name: "banned-template.png",
      keypoints: targetORB
    }
  ]
);

// 5. Check an incoming suspect image
const suspectBuffer = await fs.readFile("./suspect-image.png");
const suspectBytes = new Uint8Array(suspectBuffer);

const matchResult = await policy.checkImage(suspectBytes);

if (matchResult) {
  console.log(`Image matched! Type: ${matchResult.type}, Distance: ${matchResult.distance}, Transform: ${matchResult.transform}`);
} else {
  console.log("Image is clean.");
}

---

License

Dual-licensed under Apache-2.0 or MIT, at your choice.