[math] Add a rotation-level look-at so engine-math and Transform.lookAt share one implementation
I maintainer di solito rispondono entro 1 giorno
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Idoneità per principianti
- 48/100
- Tipo di issue
- Funzionalità
- Chiarezza
- Specificata chiaramente
- Stato di attività
- Attiva
- Stack tecnologico
- typescript
- Ambito
- backend-api-design
Direzione di ricerca
Read packages/math/src/Matrix.ts around Matrix.lookAt and packages/core/src/Transform.ts around Transform.lookAt to understand the existing conventions and basis construction. Add focused tests in tests/src/math/Quaternion.test.ts, comparing against the matrix path and checking the degenerate cases described in the issue. Done means the rotation-level API has documented semantics, the tests pass, and Transform.lookAt reuses the shared implementation.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
Summary
engine-math has no rotation-level look-at: the only look-at in the math package is Matrix.lookAt (packages/math/src/Matrix.ts:483), which produces a view matrix. Consumers that can only depend on engine-math have to rebuild the basis → quaternion conversion themselves. engine-core does exactly that — Transform.lookAt (packages/core/src/Transform.ts:528) builds the basis by hand — so the family currently ships two implementations of the same math, and the Transform one silently no-ops on degenerate input.
Proposal: add a rotation-level look-at to engine-math with an explicit degenerate contract, and let Transform.lookAt reuse it.
Current state
Matrix.lookAt(eye, target, up, out)is the only look-at inengine-math.QuaternionhasrotationEuler/rotationYawPitchRoll/rotationAxisAngle/rotationX|Y|Z, but no look-at.Transform.lookAt(targetPosition, worldUp?)does not reuse it: it buildszAxis/xAxis/yAxisby hand and callsrotMat.getRotation(this._worldRotationQuaternion).- Degenerate input is a silent no-op, and the source already carries the TODO:
if (axisLen <= MathUtil.zeroTolerance) {
// The current position and the target position are almost the same.
return; // ① eye coincides with target
}
...
if (axisLen <= MathUtil.zeroTolerance) {
// @todo:
// 1.worldUp is(0,0,0)
// 2.worldUp is parallel to zAxis
return; // ② zero up / up parallel to the view direction
}
- The
worldUp-less fallback degenerates too:xAxis.set(zAxis.z, 0, -zAxis.x)is(0,0,0)whenever the view direction is ±Y, so a target directly above/below also lands in ②. Measured with the current pinned@galacean/[email protected]:zAxis = (0, ±1, 0)→ fallbackxAxislength0. Transform.lookAthas no dedicated test — it is only called incidentally intests/src/core/MeshRenderer.test.tsandtests/src/core/Trail.test.ts.Matrix.lookAtis covered intests/src/math/Matrix.test.ts:157.
Why it matters
A public authoring tool cannot treat "silently keep the old rotation" as success. Editor's camera.lookAt (galacean/editor#3931) must work in headless/CLI, where no Engine instance exists (instantiation needs a canvas/WebGL context), and the domain layer may only depend on engine-math. It currently assembles Matrix.lookAt → Matrix.invert → Matrix.getRotation and adds its own degenerate handling; every engine-math-only consumer is in the same position.
Proposed API
/**
* Calculate the rotation of an object at `eye` looking at `target`, with `up` as the world up.
* Returns false when the direction is degenerate (eye coincides with target, `up` is zero,
* or `up` is parallel to the view direction), leaving `out` untouched.
*/
static lookAt(eye: Vector3, target: Vector3, up: Vector3, out: Quaternion): boolean;
- Same parameters as
Matrix.lookAt, so consumers keep one coordinate convention; the result is the object's world rotation (its -Z facestarget). Matrix.decompose(...): booleanis the existing precedent for a boolean "degenerate" contract.- Alternative naming:
Quaternion.lookRotation(forward, up, out)(Unity-style,forward= the direction the object's -Z should face). Either shape is fine — the point is that there is exactly one, with documented semantics.
Implementation notes
Reuse the basis flow already proven in Transform.lookAt (zAxis = normalize(eye - target); xAxis = normalize(cross(up, zAxis)); yAxis = cross(zAxis, xAxis); build the matrix; getRotation(out)), replacing both silent returns with return false. Internal temporaries should follow the Matrix._tempVec30..32 numbering convention (Quaternion currently only has _tempVector3 / _tempQuat1).
Compatibility
Pure addition; no behavior change unless Transform.lookAt starts delegating. Two decisions for that delegation:
- The
worldUp-less fallback degenerates for vertical directions (point 4). Keep the current silent no-op, or replace the fallback with a documented default (up = (0,1,0)), which is a behavior change and needs its own evaluation. Transform.lookAtreturnsvoidtoday; delegating can keep that (ignore the boolean) or returnboolean(API change).
Local verification (prototype, 20k random cases)
Quaternion.lookAtvs the existingMatrix.lookAt → invert → getRotationpath: max angle difference 2.80e-2° (both are float32, different rounding order), unit-length error 2.88e-8.- Degenerate inputs (
eye == target,up = 0,up ∥ view): all returnfalse; today those paths leave the rotation unchanged. - Vertical view with
up = (0,0,1): works. Non-orthogonalup(e.g.(0.3, 0.9, 0.1)): orthogonalized, identical toMatrix.lookAt.
Test plan
Extend tests/src/math/Quaternion.test.ts: equivalence with Matrix.lookAt (fixed cases plus randomized comparison with tolerance), the three degenerate inputs returning false with out untouched, non-orthogonal up, and unit-length output.
Downstream
After a release, galacean/editor can collapse its three-step conversion into a single call and delete the duplicated basis logic; its remaining domain-side responsibilities (hierarchy traversal, float32 representability checks) stay in the domain layer where they belong.
- Lingua principale
- TypeScript
- Stelle
- 5.9k
- Fork
- 413
- Merge medio
- 16h 17m
- PR unite (30g)
- 41
Preparare l'ambiente
- Nessun Dockerfile né file Docker Compose
- Ha un modello di pull request
- Nessuna guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di galacean/engine
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 64/100
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 85/100
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 4/5 3-5 giorni Idoneità per principianti 52/100
I maintainer di solito rispondono entro 1 giorno
-
RFC: Adopt Unity-style Collider components and hierarchical Rigidbody ownershipForse già presa Una pull request collegata a questa issue è aperta o già unita. Aperta
Difficoltà 5/5 Più di una settimana Idoneità per principianti 20/100
I maintainer di solito rispondono entro 1 giorno
-
SkinnedMeshRenderer should derive default rootBone-space localBounds from mesh and skinForse già presa Una pull request collegata a questa issue è aperta o già unita. Apertaenhancement
Difficoltà 4/5 3-5 giorni Idoneità per principianti 42/100
I maintainer di solito rispondono entro 1 giorno
Tutte le issue di galacean/engine
Issue simili
-
bug impact:low Team: SecuritySolution Team:Defend Workflows v9.6.0
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
elastic/kibana#306401 · 3 commenti ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 68/100
agentes-chat/agentes-chat#927 ·
I maintainer di solito rispondono entro 1 giorno
-
[Bug]: Webapp workspace fails to render in Safari — "Can't find variable: requestIdleCallback"Apertacomp/desktop P2 type/bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
NousResearch/hermes-agent#157702 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
I maintainer di solito rispondono entro 1 giorno
-
e2e-failure ready-to-code
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 72/100
redhat-developer/rhdh-plugin-export-overlays#4794 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno