Crate photodna_sys

Expand description

§photodna-sys

Low-level, unsafe FFI bindings to the Microsoft PhotoDNA Edge Hash Generator library.

This crate provides raw bindings to the proprietary Microsoft PhotoDNA library, which computes perceptual hashes of images for content identification purposes.

§Library Loading Model

The PhotoDNA library is designed for runtime dynamic loading via dlopen/LoadLibrary, not compile-time linking. This crate provides:

Type definitions and constants compatible with the C API
Function pointer types for all library functions
The EdgeHashGenerator struct that handles library loading and provides safe function access

§Requirements

This crate requires the proprietary Microsoft PhotoDNA SDK. You must set the PHOTODNA_SDK_ROOT environment variable to point to the SDK installation directory before building.

export PHOTODNA_SDK_ROOT=/path/to/PhotoDNA.EdgeHashGeneration-1.05.001

§Platform Support

Platform	Architecture	Support
Windows	x86_64, x86, arm64	Native library
Linux	x86_64, x86, arm64	Native library
macOS	x86_64, arm64	Native library
BSD	any	WebAssembly module (requires `wasm` feature)

§Features

native (default): Enables runtime loading of native dynamic libraries (.dll/.so).
wasm: Embeds the WebAssembly module for platforms without native library support.
bindgen: Regenerates bindings from C headers at build time (requires clang).

§Safety

All FFI functions in this crate are unsafe. Callers must ensure:

The library has been properly initialized via EdgeHashGenerator::new.
All pointers passed to functions are valid and point to sufficient memory.
Image data buffers match the specified dimensions, stride, and pixel format.
The library instance is not used after being dropped.

§Example

use photodna_sys::*;

// Initialize the library
let lib = EdgeHashGenerator::new(None, 4)?; // Use default path, 4 threads

// Prepare image data (RGB format)
let image_data: &[u8] = /* your image pixels */;
let width = 100;
let height = 100;

// Compute the hash
let mut hash = [0u8; PHOTODNA_HASH_SIZE_MAX];
unsafe {
    let result = lib.photo_dna_edge_hash(
        image_data.as_ptr(),
        hash.as_mut_ptr(),
        width,
        height,
        0, // auto-calculate stride
        PhotoDna_Default,
    );
     
    if result < 0 {
        eprintln!("Error: {}", error_code_description(result));
    }
}

Structs§

EdgeHashGenerator: The PhotoDNA Edge Hash Generator library wrapper.
HashResult: Result structure returned by border detection hash functions.

Constants§

PHOTODNA_HASH_SIZE_EDGE_V2: Size of PhotoDNA Edge V2 hash in bytes (binary format).
PHOTODNA_HASH_SIZE_EDGE_V2_BASE64: Size of PhotoDNA Edge V2 hash in bytes (Base64 format).
PHOTODNA_HASH_SIZE_MAX: Maximum hash buffer size required.
PHOTODNA_LIBRARY_VERSION: Library version string.
PhotoDna_Abgr: Pixel layout: ABGR, 4 bytes per pixel.
PhotoDna_Argb: Pixel layout: ARGB, 4 bytes per pixel.
PhotoDna_Bgr: Pixel layout: BGR, 3 bytes per pixel.
PhotoDna_Bgra: Pixel layout: BGRA, 4 bytes per pixel.
PhotoDna_CheckMemory: Check data pointers for valid allocated memory. Note: This may negatively impact performance.
PhotoDna_Cmyk: Pixel layout: CMYK, 4 bytes per pixel.
PhotoDna_Default: Default options. The matcher will return all results found.
PhotoDna_EdgeV2: Edge V2 format hash size.
PhotoDna_EdgeV2Base64: Edge V2 format hash size (Base64 encoded).
PhotoDna_ErrorBadArgument: An invalid argument was passed to the function.
PhotoDna_ErrorHashFormatInvalidCharacters: An invalid character was contained in a Base64 or Hex hash.
PhotoDna_ErrorHostMemoryAllocationFailed: Alias for memory allocation failure (host-side).
PhotoDna_ErrorImageIsFlat: The image has few or no gradients.
PhotoDna_ErrorImageTooSmall: Provided image had a dimension less than 50 pixels.
PhotoDna_ErrorInvalidHash: Hash that does not conform to PhotoDNA specifications.
PhotoDna_ErrorInvalidStride: Stride should be 0, or greater than or equal to width in bytes.
PhotoDna_ErrorInvalidSubImage: The sub region area is not within the boundaries of the image.
PhotoDna_ErrorLibraryFailure: General failure within the library.
PhotoDna_ErrorMemoryAccess: System memory exception occurred.
PhotoDna_ErrorMemoryAllocationFailed: Failed to allocate memory.
PhotoDna_ErrorNoBorder: A border was not detected for the image.
PhotoDna_ErrorNoBorderImageTooSmall: Provided image had a dimension less than 50 pixels (no border variant).
PhotoDna_ErrorSourceFormatUnknown: Not a known source image format.
PhotoDna_ErrorUnknown: An undetermined error occurred.
PhotoDna_Grey8: Pixel layout: Grayscale 8-bit, 1 byte per pixel.
PhotoDna_Grey32: Pixel layout: Grayscale 32-bit, 4 bytes per pixel.
PhotoDna_HashFormatEdgeV2: Hash output format: PhotoDNA Edge Hash V2.
PhotoDna_HashFormatEdgeV2Base64: Hash output format: PhotoDNA Edge Hash V2 Base64.
PhotoDna_HashFormatMask: Mask to isolate the hash format bits.
PhotoDna_MaxSize: Maximum hash size.
PhotoDna_NoRotateFlip: Prevent checks for rotated and/or flipped orientations.
PhotoDna_OptionNone: No options specified. See description for default behavior.
PhotoDna_Other: Use same options as specified for primary parameter.
PhotoDna_PixelLayoutMask: Mask to isolate the pixel layout bits.
PhotoDna_RemoveBorder: Check for and remove borders from the image.
PhotoDna_Rgb: Pixel layout: RGB, 3 bytes per pixel.
PhotoDna_Rgba: Pixel layout: RGBA, 4 bytes per pixel.
PhotoDna_RgbaPm: Pixel layout: RGBA with pre-multiplied alpha, 4 bytes per pixel.
PhotoDna_Test: Equivalent to Verbose + CheckMemory.
PhotoDna_Verbose: Enable debug output to stderr.
PhotoDna_YCbCr: Pixel layout: YCbCr, 3 bytes per pixel.
PhotoDna_Yuv420p: Pixel layout: YUV420P planar format. Y = 1 byte per pixel, U = 1 byte per 4 pixels, V = 1 byte per 4 pixels.

Functions§

error_code_description: Returns a human-readable description of a PhotoDNA error code.
get_library_filename: Returns the platform-specific library filename.
hash_size_for_options: Returns the expected hash size for the given options.

Type Aliases§

ErrorCode: Type alias for PhotoDNA error codes.
FnEdgeHashGeneratorInit: Function pointer type for EdgeHashGeneratorInit.
FnEdgeHashGeneratorRelease: Function pointer type for EdgeHashGeneratorRelease.
FnGetErrorNumber: Function pointer type for GetErrorNumber.
FnGetErrorString: Function pointer type for GetErrorString.
FnLibraryVersion: Function pointer type for LibraryVersion.
FnLibraryVersionMajor: Function pointer type for LibraryVersionMajor.
FnLibraryVersionMinor: Function pointer type for LibraryVersionMinor.
FnLibraryVersionPatch: Function pointer type for LibraryVersionPatch.
FnLibraryVersionText: Function pointer type for LibraryVersionText.
FnPhotoDnaEdgeHash: Function pointer type for PhotoDnaEdgeHash.
FnPhotoDnaEdgeHashBorder: Function pointer type for PhotoDnaEdgeHashBorder.
FnPhotoDnaEdgeHashBorderSub: Function pointer type for PhotoDnaEdgeHashBorderSub.
FnPhotoDnaEdgeHashSub: Function pointer type for PhotoDnaEdgeHashSub.
HashSize: Type alias for hash size identifiers.
PhotoDnaOptions: Type alias for PhotoDNA option flags.