Functions for conversion and comparison of Integer Descriptor. More...
Functions | |
| SIMD_API void * | SimdDescrIntInit (size_t size, size_t depth) |
| Initializes Integer Descriptor Engine context. More... | |
| SIMD_API size_t | SimdDescrIntEncodedSize (const void *context) |
| Gets the size in bytes of an encoded integer descriptor produced by this engine. More... | |
| SIMD_API size_t | SimdDescrIntDecodedSize (const void *context) |
| Gets the number of elements (floats) in the original descriptor. More... | |
| SIMD_API void | SimdDescrIntEncode32f (const void *context, const float *src, uint8_t *dst) |
| Encodes a 32-bit float descriptor into a compact integer representation. More... | |
| SIMD_API void | SimdDescrIntEncode16f (const void *context, const uint16_t *src, uint8_t *dst) |
| Encodes a 16-bit float descriptor into a compact integer representation. More... | |
| SIMD_API void | SimdDescrIntDecode32f (const void *context, const uint8_t *src, float *dst) |
| Decodes an integer descriptor back into a 32-bit float descriptor. More... | |
| SIMD_API void | SimdDescrIntDecode16f (const void *context, const uint8_t *src, uint16_t *dst) |
| Decodes an integer descriptor back into a 16-bit float descriptor. More... | |
| SIMD_API void | SimdDescrIntCosineDistance (const void *context, const uint8_t *a, const uint8_t *b, float *distance) |
| Calculates the cosine distance between two encoded integer descriptors. More... | |
| SIMD_API void | SimdDescrIntCosineDistancesMxNa (const void *context, size_t M, size_t N, const uint8_t *const *A, const uint8_t *const *B, float *distances) |
| Calculates all pairwise cosine distances between two sets of encoded integer descriptors (array-of-pointers form). More... | |
| SIMD_API void | SimdDescrIntCosineDistancesMxNp (const void *context, size_t M, size_t N, const uint8_t *A, const uint8_t *B, float *distances) |
| Calculates all pairwise cosine distances between two sets of encoded integer descriptors (packed/contiguous form). More... | |
| SIMD_API void | SimdDescrIntVectorNorm (const void *context, const uint8_t *a, float *norm) |
| Gets the precomputed L2 norm of an encoded integer descriptor. More... | |
Detailed Description
Functions for conversion and comparison of Integer Descriptor.
Function Documentation
◆ SimdDescrIntInit()
| void * SimdDescrIntInit | ( | size_t | size, |
| size_t | depth | ||
| ) |
Initializes Integer Descriptor Engine context.
The engine context stores the parameters needed to encode float descriptors into a compact integer representation, decode them back, and compute cosine distances directly on the encoded form without full decoding.
Each encoded descriptor produced by this engine is a byte buffer whose layout is:
- Bytes 0.. 3: 32-bit float inverse quantization scale (1 / scale).
- Bytes 4.. 7: 32-bit float minimum value (shift) used during quantization.
- Bytes 8..11: 32-bit float precomputed sum helper for dot-product reconstruction.
- Bytes 12..15: 32-bit float precomputed L2 norm of the original float descriptor.
- Bytes 16.. N: bit-packed quantized integer values, depth bits per element, packed contiguously in little-endian order.
The total byte size of the encoded buffer is returned by SimdDescrIntEncodedSize.
- Parameters
-
[in] size - a length of the original (32-bit or 16-bit float) descriptor, i.e. the number of float elements. It must be a multiple of 8 and must not exceed 32768. [in] depth - the number of bits used to represent each quantized element in the encoded descriptor. Supported values: 4, 5, 6, 7, 8.
- Returns
- a pointer to Integer Descriptor Engine context. On error it returns NULL. It must be released with using of function SimdRelease. This pointer is used in functions SimdDescrIntEncodedSize, SimdDescrIntDecodedSize, SimdDescrIntEncode32f, SimdDescrIntEncode16f, SimdDescrIntDecode32f, SimdDescrIntDecode16f, SimdDescrIntCosineDistance, SimdDescrIntCosineDistancesMxNa, SimdDescrIntCosineDistancesMxNp, SimdDescrIntVectorNorm.
◆ SimdDescrIntEncodedSize()
| size_t SimdDescrIntEncodedSize | ( | const void * | context | ) |
Gets the size in bytes of an encoded integer descriptor produced by this engine.
The encoded descriptor consists of a 16-byte header (4 x 32-bit floats storing the inverse quantization scale, the minimum value, a precomputed sum helper, and the precomputed L2 norm) followed by the bit-packed quantized integer data. The total size equals 16 + ceil(size * depth / 8), where size and depth are the values passed to SimdDescrIntInit.
- Parameters
-
[in] context - a pointer to Integer Descriptor Engine context. It must be created by function SimdDescrIntInit and released by function SimdRelease.
- Returns
- the size in bytes of an encoded integer descriptor.
◆ SimdDescrIntDecodedSize()
| size_t SimdDescrIntDecodedSize | ( | const void * | context | ) |
Gets the number of elements (floats) in the original descriptor.
This is the value of the size parameter that was passed to SimdDescrIntInit. It equals the number of 32-bit or 16-bit float elements in the uncompressed descriptor, and is the required length of the src buffer for SimdDescrIntEncode32f / SimdDescrIntEncode16f and the dst buffer for SimdDescrIntDecode32f / SimdDescrIntDecode16f.
- Parameters
-
[in] context - a pointer to Integer Descriptor Engine context. It must be created by function SimdDescrIntInit and released by function SimdRelease.
- Returns
- the number of float elements in the original (decoded) descriptor.
◆ SimdDescrIntEncode32f()
| void SimdDescrIntEncode32f | ( | const void * | context, |
| const float * | src, | ||
| uint8_t * | dst | ||
| ) |
Encodes a 32-bit float descriptor into a compact integer representation.
The function quantizes each element of the input float array linearly into the range [0, 2^depth - 1], where depth was specified at context creation. The encoding procedure:
- Finds the minimum and maximum values of the source descriptor.
- Computes a quantization scale: scale = (2^depth - 1) / (max - min).
- Quantizes each element: q[i] = round((src[i] - min) * scale).
- Packs the quantized values bit-by-bit (depth bits per element) into the output buffer starting at byte offset 16.
- Writes a 16-byte header at the beginning of dst containing four 32-bit floats: inverse scale (1/scale), minimum value (min), a precomputed sum helper used for dot-product reconstruction, and the precomputed L2 norm of the original descriptor.
The precomputed norm and sum helper in the header allow SimdDescrIntCosineDistance and related functions to compute cosine distances without decoding the descriptor.
- Parameters
-
[in] context - a pointer to Integer Descriptor Engine context. It must be created by function SimdDescrIntInit and released by function SimdRelease. [in] src - a pointer to the input 32-bit float descriptor. The number of elements must equal the value returned by SimdDescrIntDecodedSize. [out] dst - a pointer to the output encoded integer descriptor. The buffer size in bytes must be at least the value returned by SimdDescrIntEncodedSize.
◆ SimdDescrIntEncode16f()
| void SimdDescrIntEncode16f | ( | const void * | context, |
| const uint16_t * | src, | ||
| uint8_t * | dst | ||
| ) |
Encodes a 16-bit float descriptor into a compact integer representation.
This function is identical in behavior to SimdDescrIntEncode32f except that the input descriptor elements are 16-bit floats (half precision, stored as uint16_t). Each element is first converted to 32-bit float internally, then quantized and packed in the same way. The output encoded descriptor format is identical to that produced by SimdDescrIntEncode32f and is fully compatible with all decode and distance functions.
- Parameters
-
[in] context - a pointer to Integer Descriptor Engine context. It must be created by function SimdDescrIntInit and released by function SimdRelease. [in] src - a pointer to the input 16-bit float descriptor (half precision, stored as uint16_t). The number of elements must equal the value returned by SimdDescrIntDecodedSize. [out] dst - a pointer to the output encoded integer descriptor. The buffer size in bytes must be at least the value returned by SimdDescrIntEncodedSize.
◆ SimdDescrIntDecode32f()
| void SimdDescrIntDecode32f | ( | const void * | context, |
| const uint8_t * | src, | ||
| float * | dst | ||
| ) |
Decodes an integer descriptor back into a 32-bit float descriptor.
The function reconstructs the original float values from the bit-packed quantized data using the inverse scale and minimum value stored in the 16-byte header of the encoded descriptor. Each reconstructed element is computed as: dst[i] = q[i] * invScale + min, where invScale and min are read from the first two 32-bit floats of src. The decoded values are approximations of the original floats; precision depends on depth.
- Parameters
-
[in] context - a pointer to Integer Descriptor Engine context. It must be created by function SimdDescrIntInit and released by function SimdRelease. [in] src - a pointer to the encoded integer descriptor. The buffer size in bytes must be at least the value returned by SimdDescrIntEncodedSize. [out] dst - a pointer to the output 32-bit float descriptor. The number of elements must equal the value returned by SimdDescrIntDecodedSize.
◆ SimdDescrIntDecode16f()
| void SimdDescrIntDecode16f | ( | const void * | context, |
| const uint8_t * | src, | ||
| uint16_t * | dst | ||
| ) |
Decodes an integer descriptor back into a 16-bit float descriptor.
This function is identical in behavior to SimdDescrIntDecode32f except that each reconstructed element is converted from 32-bit float to 16-bit float (half precision, stored as uint16_t) before being written to the output buffer.
- Parameters
-
[in] context - a pointer to Integer Descriptor Engine context. It must be created by function SimdDescrIntInit and released by function SimdRelease. [in] src - a pointer to the encoded integer descriptor. The buffer size in bytes must be at least the value returned by SimdDescrIntEncodedSize. [out] dst - a pointer to the output 16-bit float descriptor (half precision, stored as uint16_t). The number of elements must equal the value returned by SimdDescrIntDecodedSize.
◆ SimdDescrIntCosineDistance()
| void SimdDescrIntCosineDistance | ( | const void * | context, |
| const uint8_t * | a, | ||
| const uint8_t * | b, | ||
| float * | distance | ||
| ) |
Calculates the cosine distance between two encoded integer descriptors.
The cosine distance is defined as: distance = 1 - dot(a, b) / (||a|| * ||b||), where a and b are treated as vectors in the original float space. The function computes the integer dot product directly on the bit-packed data and then reconstructs the true float dot product using the quantization scale and shift stored in the 16-byte headers of the encoded descriptors. The L2 norms are read directly from the precomputed values in the headers, avoiding full decoding. The result is clamped to the range [0, 2].
- Note
- An encoded integer descriptor is produced by SimdDescrIntEncode32f or SimdDescrIntEncode16f. Its size in bytes is determined by function SimdDescrIntEncodedSize.
- Parameters
-
[in] context - a pointer to Integer Descriptor Engine context. It must be created by function SimdDescrIntInit and released by function SimdRelease. [in] a - a pointer to the first encoded integer descriptor. [in] b - a pointer to the second encoded integer descriptor. [out] distance - a pointer to a 32-bit float that receives the cosine distance in the range [0, 2].
◆ SimdDescrIntCosineDistancesMxNa()
| void SimdDescrIntCosineDistancesMxNa | ( | const void * | context, |
| size_t | M, | ||
| size_t | N, | ||
| const uint8_t *const * | A, | ||
| const uint8_t *const * | B, | ||
| float * | distances | ||
| ) |
Calculates all pairwise cosine distances between two sets of encoded integer descriptors (array-of-pointers form).
Computes the M x N matrix of cosine distances, where distances[i * N + j] is the cosine distance between the i-th descriptor in A and the j-th descriptor in B. See SimdDescrIntCosineDistance for the definition of cosine distance. This variant accepts the descriptors through arrays of pointers, which allows non-contiguous memory layouts. For contiguous storage use SimdDescrIntCosineDistancesMxNp instead. The implementation automatically selects cache-friendly blocking strategies.
- Note
- An encoded integer descriptor is produced by SimdDescrIntEncode32f or SimdDescrIntEncode16f. Its size in bytes is determined by function SimdDescrIntEncodedSize.
- Parameters
-
[in] context - a pointer to Integer Descriptor Engine context. It must be created by function SimdDescrIntInit and released by function SimdRelease. [in] M - the number of descriptors in set A (number of rows in the output matrix). [in] N - the number of descriptors in set B (number of columns in the output matrix). [in] A - an array of M pointers, each pointing to an encoded integer descriptor. [in] B - an array of N pointers, each pointing to an encoded integer descriptor. [out] distances - a pointer to the output M x N matrix of 32-bit float cosine distances stored in row-major order. The buffer must hold at least M * N elements.
◆ SimdDescrIntCosineDistancesMxNp()
| void SimdDescrIntCosineDistancesMxNp | ( | const void * | context, |
| size_t | M, | ||
| size_t | N, | ||
| const uint8_t * | A, | ||
| const uint8_t * | B, | ||
| float * | distances | ||
| ) |
Calculates all pairwise cosine distances between two sets of encoded integer descriptors (packed/contiguous form).
Computes the M x N matrix of cosine distances, where distances[i * N + j] is the cosine distance between the i-th descriptor in A and the j-th descriptor in B. See SimdDescrIntCosineDistance for the definition of cosine distance. This variant accepts the descriptors as two flat contiguous arrays, where descriptor i starts at A + i * encodedSize and descriptor j starts at B + j * encodedSize, with encodedSize returned by SimdDescrIntEncodedSize. For non-contiguous memory layouts use SimdDescrIntCosineDistancesMxNa instead.
- Note
- An encoded integer descriptor is produced by SimdDescrIntEncode32f or SimdDescrIntEncode16f. Its size in bytes is determined by function SimdDescrIntEncodedSize.
- Parameters
-
[in] context - a pointer to Integer Descriptor Engine context. It must be created by function SimdDescrIntInit and released by function SimdRelease. [in] M - the number of descriptors in set A (number of rows in the output matrix). [in] N - the number of descriptors in set B (number of columns in the output matrix). [in] A - a pointer to the contiguous array of M encoded integer descriptors. [in] B - a pointer to the contiguous array of N encoded integer descriptors. [out] distances - a pointer to the output M x N matrix of 32-bit float cosine distances stored in row-major order. The buffer must hold at least M * N elements.
◆ SimdDescrIntVectorNorm()
| void SimdDescrIntVectorNorm | ( | const void * | context, |
| const uint8_t * | a, | ||
| float * | norm | ||
| ) |
Gets the precomputed L2 norm of an encoded integer descriptor.
The L2 norm of the original float descriptor is computed and stored in the 16-byte header of the encoded descriptor during encoding (by SimdDescrIntEncode32f or SimdDescrIntEncode16f). This function retrieves that precomputed value without performing any additional computation. The norm equals the Euclidean length of the original float descriptor before quantization.
- Note
- An encoded integer descriptor is produced by SimdDescrIntEncode32f or SimdDescrIntEncode16f. Its size in bytes is determined by function SimdDescrIntEncodedSize.
- Parameters
-
[in] context - a pointer to Integer Descriptor Engine context. It must be created by function SimdDescrIntInit and released by function SimdRelease. [in] a - a pointer to the encoded integer descriptor. [out] norm - a pointer to a 32-bit float that receives the precomputed L2 norm of the original float descriptor.