API reference

This page is intentionally simple for now. Replace with generated stubs later if preferred.

ImageHashIndex

Main in-memory index.

$index = new ImageHashIndex();

add()

Add a precomputed hash.

$index->add(string $id, string $hash): void

Example:

$index->add('image-1', 'f123456789abcdef');

search()

Search by hash.

$index->search(string $hash, int $maxDistance = 10, int $limit = 10): array

Example:

$matches = $index->search('f123456789abcdef', maxDistance: 5, limit: 20);

searchImage()

Search by image.

$matches = $index->searchImage('exmaple.png', maxDistance: 5, limit: 20);

nearest()

Find the nearest indexed match.

$index->nearest(string $hash): array

Example:

$index->add('near', 'aaaaaaaaaaaaaaab');
$index->add('far', 'ffffffffffffffff');
$nearest = $index->nearest('aaaaaaaaaaaaaaaa');

Output:

[
    'id' => 'near'
    'distance' => 2
]

nearestImage()

Find the closest matching image.

$index->nearest(string $path): array

Exmaple:

$index->addImage('cat', 'cat.jpg');
$index->addImage('dog', 'dog.jpg');
$match = $index->nearestImage('cat-cropped.jpg');

Output:

[
    'id' => 'cat',
    'distance' => 2
]

save()

Save the index to disk.

$index->save(string $path): void

load()

Load a saved index.

$index = ImageHashIndex::load(string $path);

Result shape

Expected result shape:

[
    [
        'id' => 'image-1',
        'distance' => 0,
    ],
    [
        'id' => 'image-2',
        'distance' => 2,
    ],
]

stats

Show curent index statistics

$index->stats()

$stats = $index->stats();
print_r($stats);

Example output

[
    'hashes' => 5000000
    'buckets' => 65536
    'memory_bytes' => 184320000
]

Field	Description
hashes	Total hashes stored in the index
buckets	Internal bucket count used for candidate pruning
memory_bytes	Approximate memory used by the index