docs: clarify unit, coordinate system, and HID origin for LampInfo.Position and LampArray.BoundingBox

[Copilot]

LampInfo.Position and LampArray.BoundingBox lacked any specification of units, coordinate system handedness, axis orientation, or origin—forcing developers to reverse-engineer scale empirically.

lampinfo_position.md

• Description now explicitly states values are in meters relative to the front-top-left corner of the bounding box
• Property-value section describes each Vector3 axis (X=right, Y=down, Z=away from user)
• New Remarks section covering:
  • Left-handed coordinate system with explicit +X/+Y/+Z directions
  • Origin definition: (0, 0, 0) = front-top-left corner of LampArray.BoundingBox
  • HID provenance: values converted from micrometers (µm ÷ 1,000,000) per the HID LampArray descriptor
• See-also links added for BoundingBox, HID spec, and Dynamic lighting docs

lamparray_boundingbox.md

• Added explicit left-handed coordinate system block with +X/+Y/+Z axis directions (parallel with Position page)
• Added note that extents originate from the HID descriptor in micrometers, converted to meters by the WinRT layer

• Fixes Missing Unit Specification for LampInfo.Position #2539

[Copilot]

🟡 Changes recommended

The documented axis directions and origin conflict with the LampArray/HID contract and must be corrected before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This pull request clarifies units, coordinate systems, origins, and HID provenance for LampArray spatial properties.

Changes:

• Documents LampInfo.Position values, axes, origin, and HID conversion.
• Adds coordinate-system and HID-derived extent details to LampArray.BoundingBox.
• Adds related references.

File summaries

File	Summary
windows.devices.lights/lampinfo_position.md	Documents position units, axes, origin, and HID conversion.
windows.devices.lights/lamparray_boundingbox.md	Documents bounding-box axes, origin, and HID-derived meter conversion.

Review details

Suppressed comments (3)

windows.devices.lights/lamparray_boundingbox.md:29

• The handedness label conflicts with the axis directions documented here: +X to the right crossed with +Y downward points away from the user, which is the listed +Z direction, so these axes form a right-handed basis. Please reconcile the text with the API/HID contract (for example, change the label to right-handed or correct the +Z direction); the current combination will lead consumers to build incorrect 3D transforms.

The coordinate system is left-handed, with the origin at the front-top-left corner of the bounding box:
- **+X** extends to the right.
- **+Y** extends downward.
- **+Z** extends away from the user (into the device).

windows.devices.lights/lamparray_boundingbox.md:29

• This orientation block reverses the HID LampArray contract: the origin is the upmost, farthest, left-hand corner and the axes are X left-to-right, Y farthest-to-closest, and Z top-to-bottom. It also leaves the following origin sentence inconsistent. Please replace this new block and align/remove that sentence as part of the same correction.

The coordinate system is left-handed, with the origin at the front-top-left corner of the bounding box:
- **+X** extends to the right.
- **+Y** extends downward.
- **+Z** extends away from the user (into the device).

windows.devices.lights/lampinfo_position.md:14

• The HID LampArray contract does not use the front corner as the origin: it defines (0, 0, 0) at the upmost, farthest, left-hand corner of the bounding box. Calling this the front corner reverses the reference point for depth and makes the documented positions incompatible with the descriptor.

Gets the position of the lamp within the lamp array, expressed in meters relative to the front-top-left corner of the array's bounding box.

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.