Improve SimdDescrInt API documentation in SimdLib.h - #360
Merged
ermig1979 merged 3 commits intoJun 3, 2026
Conversation
Copilot
AI
changed the title
Improve SimdDescrInt function descriptions in SimdLib.h
Improve SimdDescrInt API documentation in SimdLib.h
Jun 2, 2026
Copilot created this pull request from a session on behalf of
ermig1979
June 2, 2026 16:20
View session
ermig1979
marked this pull request as ready for review
June 2, 2026 16:21
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates Doxygen documentation in SimdLib.h, primarily expanding and clarifying the Integer Descriptor Engine (SimdDescrInt*) API, including encoded descriptor layout and cosine-distance semantics. It also includes a set of broader documentation clarifications for several image conversion, binarization, conditional, and copy APIs.
Changes:
- Expanded
SimdDescrInt*docs with encoded buffer layout, encode/decode pipeline details, and cosine-distance matrix conventions. - Clarified behavior/constraints for several image conversion (BGR→Lab/RGB/YUV) and binarization/conditional/copy APIs.
- Minor doc-logic and parameter-description fixes (including pseudocode and boundary/stride explanations).
Comment on lines
2541
to
2543
| All images must have 8-bit gray format and must have the same width and height. | ||
| Image width and height must be greater than neighborhood. | ||
|
|
| - 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. |
| starting at byte offset 16. | ||
| 5. Writes a 16-byte header at the beginning of \a 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. |
Comment on lines
+2969
to
+2973
| where \a a and \a 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. |
Comment on lines
+3040
to
+3043
| 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. |
| \param [in] a - a pointer to integer descriptor. | ||
| \param [out] norm - a pointer to result 32-bit float norm. | ||
| \param [in] a - a pointer to the encoded integer descriptor. | ||
| \param [out] norm - a pointer to a 32-bit float that receives the precomputed L2 norm of the original float descriptor. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The existing Doxygen comments for the
SimdDescrIntfamily were superficial, omitting the encoding format, quantization algorithm, and the role of the precomputed header fields — all of which are non-obvious and critical for correct usage.Changes
SimdDescrIntInit— Documents the exact binary layout of every encoded descriptor:1/scale)depthbits per element, little-endianSimdDescrIntEncodedSize— Adds the formula:16 + ceil(size * depth / 8).SimdDescrIntDecodedSize— Clarifies it returns thesizepassed toInit; lists which encode/decode calls require it as a buffer length.SimdDescrIntEncode32f/SimdDescrIntEncode16f— Documents the full encoding pipeline: min/max scan → scale =(2^depth−1)/(max−min)→ round quantize → bit-pack → header write. Notes thatEncode16fconverts FP16→FP32 internally before the same pipeline.SimdDescrIntDecode32f/SimdDescrIntDecode16f— Documents reconstruction formuladst[i] = q[i] * invScale + min; notes precision isdepth-dependent.Decode16fadditionally converts each output to FP16.SimdDescrIntCosineDistance— Adds formal definition (1 − dot(a,b)/(‖a‖·‖b‖)), explains that the integer dot product is computed directly on bit-packed data using header scale/shift, and that L2 norms are read from precomputed header fields (no decoding). Result is clamped to [0, 2].SimdDescrIntCosineDistancesMxNa/MxNp— Clarifies M×N row-major output layout. Distinguishes the two variants:MxNatakes an array of pointers (non-contiguous memory);MxNptakes flat contiguous arrays with stridei * encodedSize.SimdDescrIntVectorNorm— Clarifies it reads the precomputed L2 norm from the header (no recomputation).