Skip to content

DOC: Document the unit-length preconditions of orientation conversions - #81

Closed
imikejackson wants to merge 1 commit into
BlueQuartzSoftware:developfrom
imikejackson:doc/orientation-preconditions
Closed

imikejackson wants to merge 1 commit into
BlueQuartzSoftware:developfrom
imikejackson:doc/orientation-preconditions

Conversation

@imikejackson

Copy link
Copy Markdown
Collaborator

Summary

Four conversion and normalization functions assume unit-length (or nonzero) input but did not say so. This PR changes doc comments only; no behavior changes.

  • AxisAngle::toQuaternion() and AxisAngle::toOrientationMatrix() do not normalize the axis. With axis (0, 0, 2) and angle 1 rad, they return a quaternion of length 1.30 and a matrix with om[8] = 2.38. AxisAngle::isValid() already rejects a non-unit axis (result -2), so the class already requires a unit axis. The doc comments now state this precondition.
  • Quaternion::toOrientationMatrix() does not normalize the quaternion. The result is scaled by the squared length: (0, 0, 0, 2) gives om[0] = 4, and the zero quaternion gives the zero matrix (not NaN). Quaternion::isValid() already rejects both. The doc comment now states the precondition and suggests calling normalize() first.
  • Matrix3X1::normalize() has no zero-length check, so the zero vector gives NaN components. The doc comment now states the precondition and points to the static normalize(i, j, k) overload, which returns false for a zero vector.

I did not add guards. No result is correct for a non-rotation, and an added guard would only replace one wrong value with another.

Test Plan

  • Doc comments only. I checked the documented behavior on develop with a standalone program (output quoted above).
  • Linux x64, Release: full ctest suite passes, 429/429.

Related Issue

Related to BlueQuartzSoftware/simplnx#1891 (a zero quaternion gives a zero orientation matrix in ComputeCAxisLocationsFilter) and BlueQuartzSoftware/simplnx#1875 (zero-length vectors). The fixes for those filters belong in simplnx: each filter checks its input before it calls these functions.

🤖 Generated with Claude Code

* AxisAngle::toQuaternion() and toOrientationMatrix() do not normalize the
  axis; a non-unit axis gives a non-unit quaternion or a matrix that is not
  a rotation. isValid() already requires a unit axis, so the precondition
  is documented and behavior is unchanged.
* Quaternion::toOrientationMatrix() does not normalize the quaternion; the
  result is scaled by the squared length and the zero quaternion gives the
  zero matrix. Documented; behavior is unchanged.
* Matrix3X1::normalize() has no zero-length check; the zero vector gives
  NaN components. Documented, with a pointer to the static
  normalize(i, j, k) overload that reports a zero vector.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@imikejackson imikejackson mentioned this pull request Nov 13, 2026
7 tasks done
@imikejackson

Copy link
Copy Markdown
Collaborator Author

Closed in favor of #86, which merges this branch (with its history) together with the other open EbsdLib fixes for the next release, so simplnx can build against one EbsdLib branch. The branch is kept.

🤖 Generated with Claude Code

@imikejackson
imikejackson deleted the doc/orientation-preconditions branch November 13, 2026 16:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant