getPoseMatrix() returns a zero matrix — pose3d is never populated in the live path

[kalwalt]

Summary

WebARKit::getPoseMatrix() (the cv::Mat / 4×4 pose, bound to JS) returns a zero matrix at runtime. It is wired to WebARKitPatternTrackingInfo::pose3d, but the live tracking path never writes pose3d.

Discovered during the #50 dead-code audit while confirming the matrix getters as intentional public API.

Detail — the chain

getPoseMatrix() → manager::getPoseMatrix() → tracker::getPoseMatrix():

cv::Mat getPoseMatrix() { return _patternTrackingInfo.pose3d; }

pose3d is initialised to zeros in the ctor (WebARKitPattern.cpp):

pose3d = cv::Mat::zeros(4, 4, CV_64FC1);

In the live processFrame path the pose flows through _pose → transMat → trans, not pose3d:

_patternTrackingInfo.cameraPoseFromPoints(_pose, objPoints, imgPoints, ...); // writes _pose (local)
_patternTrackingInfo.getTrackablePose(_pose);   // memcpy _pose -> transMat
_patternTrackingInfo.updateTrackable();          // transMat -> trans (handedness + scale, #42)
_patternTrackingInfo.computeGLviewMatrix(_pose); // _pose -> glViewMatrix

pose3d is written only by computePose() / invertPose(), both of which are dead (only cameraPoseFromPoints is used; computePose's sole call site is commented). So pose3d keeps its zero value forever.

getPoseMatrix2() (the float[3][4] / trans) is the one actually used by the examples (via WebARKitController.getPoseMatrix() → getPoseMatrix2()), which is why this has gone unnoticed: nothing reads getPoseMatrix() today.

Impact

getPoseMatrix() is part of the public JS API. A downstream user who calls it directly (doing their own pose math rather than using our examples) gets a 4×4 of zeros.

Fix options

1. Populate pose3d in the live path (write it in/after cameraPoseFromPoints).
2. Or have getPoseMatrix() derive its 4×4 from the live trans/_pose data (single source of truth).

Either way the dead computePose / invertPose / computeGLviewMatrix() (no-arg) become removable (tracked in #50).

Related

• Code audit: find duplicated / orphan / unused code in WebARKit (excluding vendored lib/SRC and AR/ headers) #50 (code audit) — logged there as a KEEP + FIX item; see docs/audit-dead-code-issue50.md in webarkit-testing.
• Likely a good moment to also clarify the confusing getPoseMatrix / getPoseMatrix2 naming (separate discussion).

[kalwalt]

Naming clarification to ride along this fix (agreed)

While fixing the zero-matrix bug, also rename the two pose getters — the 2 suffix hides that they differ in both coordinate convention and shape:

current	returns	→ rename to
getPoseMatrix	raw OpenCV pose, 4×4 (the one being fixed here)	getPoseMatrixCV
getPoseMatrix2	right-handed / GL-corrected pose (trans, D·R·D #42)	getPoseMatrixGL

Touches bindings.cpp, WebARKitJS.{h,cpp}, WebARKitManager, WebARKitTracker, and (in webarkit-testing) the WebARKitController.js wrapper + examples.

Rollout still to decide in the PR: hard rename vs. keeping the old names as one-release deprecated aliases (the API is public, so a downstream caller using getPoseMatrix2() would break on a hard rename).

Logged in the #50 audit doc (docs/audit-dead-code-issue50.md, decision table) as KEEP-API + FIX + RENAME.