match op• 資料種類:qimage × qimage → qimage
• 呼叫: import fullseye as fs; fs.ledger.quat_correlate(qimage, template) -> 'np.ndarray'(要直接呼叫實作,import quatimage; quatimage.quat_correlate(qimage, template) -> 'np.ndarray';從台帳取用則 opsquat.get("quat_correlate"))
四元數互相關 sum_s conj(a(s)) * b(s+t)。→ (H, W, 4)。
> 以下的詳細說明為原文 —— 摘要與標題已翻譯。
Colour template matching that keeps the colour geometry, not just the colour magnitude. The scalar part of the result is sum (a_R b_R + a_G b_G + a_B b_B) — exactly the sum of the three per-channel correlations, i.e. what a channelwise pipeline computes and all it computes. The *vector* part is -sum (a x b), the accumulated colour cross-product, and it is zero exactly when the two colour fields are parallel. So the same call answers "how well does it match?" (scalar part) and "in what way does the colour fail to line up?" (vector part).
Measured on a 32x32 patch whose colours lie in the red-green plane, matched against a copy of itself rotated about the blue axis. The scalar part is cos(angle) times the self-correlation, exactly, and atan2(|vector|, scalar) returns the rotation angle:
=========== ================== ================= ==================
rotation scalar/self ratio cos(angle) angle recovered
=========== ================== ================= ==================
0 deg 1.000000 1.000000 0.000000 deg
30 deg 0.866025 0.866025 30.000000 deg
90 deg 0.000000 0.000000 90.000000 deg
=========== ================== ================= ==================
with the vector direction at (0.000, 0.000, -1.000) — the negative of the rotation axis, because the conjugate sits on the left of the product. A channelwise pipeline has no term that can produce any of that: the cross-products are *cross*-channel products, and three independent channel correlations never form them. (Verified in the same test: the scalar part equals the summed per-channel correlation to 0.0 exactly, so the channelwise baseline recovers the scalar part and nothing else.)
The exact reading needs the colours to lie in the plane orthogonal to the rotation axis, and the docstring says so because the general case is biased. For a colour field with a component along the axis, the vector part picks up terms in a_z and the recovered angle is wrong: measured on a uniform-random colour patch rotated 30 degrees about blue, the same formula returns 22.524 degrees on an axis of (0.247, 0.419, -0.874) instead of (0, 0, -1). That is a quiet wrong number, it is inherent to summing per-pixel cross products, and it is not detectable from the result — so the precondition is part of the contract.
Both inputs must be pure quaternion images for any of the above to hold; a non-zero scalar part is not refused (it is algebraically fine) but it contributes to both parts and the colour interpretation stops applying.
The correlation is circular (computed with FFTs, like filters_freq's family): a template near the border wraps around. Pad the inputs if that matters. Shapes must match exactly; a smaller template must be zero-padded into the image's shape by the caller, because silently choosing a padding origin would move the peak.
Raises ValueError: either input is not a valid (H, W, 4) field, or the two shapes differ.
• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。
• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。
• 演算法的正典(作者、年份)與用途見上面的族使用指南。
• quaternion_monogenic — py -3.11 examples/quaternion_monogenic.py
qimage 作為輸入)quaternion_to_rgb · quat_norm · quat_conjugate_image · quat_normalize_image · quat_image_multiply · monogenic_amplitude · monogenic_phase · monogenic_orientation
match)—
*Provenance: quatimage.py — QUAT 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.