useMetrics

Summary

Performs unit conversion between the point unit (px) used by 2D GUI and the physical world unit (m) used by 3D space.

On visionOS, the default mapping is roughly 1360px ≈ 1 meter, but this conversion is not always fixed:

If the Spatial Scene container is of type window, or if the scene type is volume and worldScaling in the initialization properties is set to dynamic, then the conversion between these two units is not fixed. See worldScalingCompensation.

The conversion ratio also differs across spatial computing platforms, so this API should be used consistently for unit conversion.

Signature

import { useMetrics } from "@webspatial/react-sdk";

function UnitConvertTest() {
  const { pointToPhysical, physicalToPoint } = useMetrics();

  return (
    <>
      <pre>
        Scaled conversion
        {"\n"}
        physicalToPoint(1): {physicalToPoint(1)}
        {"\n"}
        pointToPhysical(1): {pointToPhysical(1)}
      </pre>

      <pre>
        Unscaled conversion
        {"\n"}
        physicalToPoint(1):{" "}
        {physicalToPoint(1, { worldScalingCompensation: "unscaled" })}
        {"\n"}
        pointToPhysical(1):{" "}
        {pointToPhysical(1, { worldScalingCompensation: "unscaled" })}
      </pre>
    </>
  );
}

Parameters

None.

Return Shape

type WorldScalingCompensation = "scaled" | "unscaled";

type MetricConvertOptions = {
  worldScalingCompensation?: WorldScalingCompensation;
};

type UseMetricsReturn = {
  pointToPhysical: (value: number, options?: MetricConvertOptions) => number;
  physicalToPoint: (value: number, options?: MetricConvertOptions) => number;
};

worldScalingCompensation determines whether the current Spatial Scene container's worldScaling should be compensated during the conversion.

• scaled: the conversion result matches the size perceived by the user after automatic scaling from worldScaling
• unscaled: returns a stable physical-world value that does not change with worldScaling

pointToPhysical

pointToPhysical(value: number, options?: MetricConvertOptions): number

physicalToPoint

physicalToPoint(value: number, options?: MetricConvertOptions): number