@ericchen1990/pano-view 0.1.4 → 0.1.6

package/README.md

@@ -65,7 +65,18 @@ export function TileExample() {
 }
 ```
 
-The first `multires` value is the tile size. Remaining values are ascending cube-face sizes for `l1`, `l2`, and later levels. The default preview is `${baseUrl}/previews/cube-vertical.webp`, with faces stacked as `l/f/r/b/u/d`. Use `previewFaceOrder` when a preview atlas uses a different top-to-bottom order.
+The first `multires` value is the tile size. Remaining values are ascending cube-face sizes for `l1`, `l2`, and later levels. The default preview is `${baseUrl}/previews/cube-vertical.webp`, with six square faces stacked from top to bottom as `l/f/r/b/u/d`. Use `previewFaceOrder` when an atlas uses a different order:
+
+```tsx
+<Tile
+  baseUrl="/panoramas/room"
+  multires="512,1000,2000"
+  previewUrl="/panoramas/room/previews/cube-vertical.webp"
+  previewFaceOrder={["l", "f", "r", "b", "u", "d"]}
+/>
+```
+
+`previewFaceOrder` must list the six face codes in their top-to-bottom atlas order: `f`, `r`, `b`, `l`, `u`, and `d`.
 
 During rapid rotation or zoom, loaded tiles remain visible while newly visible tiles use their parent level or the preview as a local fallback.
 
@@ -217,8 +228,8 @@ export function PlacementExample() {
 
 `normalizePanoPosition`, `normalizePanoYaw`, `clampPanoPitch`, and
 `vector3ToPanoPosition` are also exported for controlled authoring flows. Yaw
-is normalized to `[-180, 180)`. Pitch is clamped to `[-89.9, 89.9]` to avoid
-the spherical-coordinate singularity at the poles.
+is normalized to `[-180, 180)`. Pitch is clamped to `[-90, 90]`; at either
+pole, yaw is normalized to `0` because it does not identify a unique point.
 
 ## Shared hotspot contract and saved definitions
 
@@ -326,6 +337,9 @@ placement properties:
 - `scaleMode="fov"` (default) lets a hotspot grow when the user zooms in.
   `scaleMode="fixed"` compensates for FOV changes and keeps its screen size
   close to the size at `referenceFov` (default `75`).
+- `rotation` rotates the hotspot around its own normal in degrees. `scale`
+  applies an overall positive multiplier to its angular width and height and
+  defaults to `1`.
 
 ```tsx
 <ImageHotspot
@@ -336,6 +350,8 @@ placement properties:
   height={6}
   mode="billboard"
   distance={14}
+  rotation={-12}
+  scale={1.25}
   scaleMode="fixed"
   src="/hotspots/callout.webp"
 />

package/dist/index.cjs

@@ -52,7 +52,7 @@ var import_react4 = require("react");
 var import_fiber = require("@react-three/fiber");
 var import_react = require("react");
 var import_three = require("three");
-var MAX_PITCH = 89.9;
+var MAX_PITCH = 90;
 var INERTIA_ROTATION_DAMPING = 8;
 var INERTIA_ZOOM_DAMPING = 12;
 var DEFAULT_ROTATE_DAMPING = 14;
@@ -578,9 +578,10 @@ var import_three3 = require("three");
 var import_three2 = require("three");
 
 // src/hotspot/types.ts
-var MAX_HOTSPOT_PITCH = 89.9;
+var MAX_HOTSPOT_PITCH = 90;
 
 // src/hotspot/coordinates.ts
+var POLE_EPSILON_DEGREES = 1e-6;
 function normalizePanoYaw(yaw) {
   if (!Number.isFinite(yaw)) {
     return 0;
@@ -591,12 +592,18 @@ function clampPanoPitch(pitch) {
   if (!Number.isFinite(pitch)) {
     return 0;
   }
-  return import_three2.MathUtils.clamp(pitch, -MAX_HOTSPOT_PITCH, MAX_HOTSPOT_PITCH);
+  const clamped = import_three2.MathUtils.clamp(
+    pitch,
+    -MAX_HOTSPOT_PITCH,
+    MAX_HOTSPOT_PITCH
+  );
+  return Math.abs(clamped) >= MAX_HOTSPOT_PITCH - POLE_EPSILON_DEGREES ? Math.sign(clamped) * MAX_HOTSPOT_PITCH : clamped;
 }
 function normalizePanoPosition(position) {
+  const pitch = clampPanoPitch(position.pitch);
   return {
-    yaw: normalizePanoYaw(position.yaw),
-    pitch: clampPanoPitch(position.pitch)
+    yaw: Math.abs(pitch) === MAX_HOTSPOT_PITCH ? 0 : normalizePanoYaw(position.yaw),
+    pitch
   };
 }
 function panoPositionToVector3(position, radius = 1) {
@@ -724,7 +731,7 @@ var PanoView = (0, import_react4.forwardRef)(
     const normalizedInitialView = (0, import_react4.useMemo)(
       () => ({
         yaw: initialView?.yaw ?? DEFAULT_VIEW.yaw,
-        pitch: initialView?.pitch ?? DEFAULT_VIEW.pitch,
+        pitch: clampPanoPitch(initialView?.pitch ?? DEFAULT_VIEW.pitch),
         fov: Math.max(
           normalizedMinFov,
           Math.min(initialView?.fov ?? DEFAULT_VIEW.fov, normalizedMaxFov)
@@ -2449,6 +2456,9 @@ function angularSizeToWorldSize(size, radius) {
   const safeSize = Number.isFinite(size) ? import_three9.MathUtils.clamp(Math.abs(size), MIN_ANGULAR_SIZE, MAX_ANGULAR_SIZE) : MIN_ANGULAR_SIZE;
   return 2 * radius * Math.tan(import_three9.MathUtils.degToRad(safeSize) / 2);
 }
+function resolveScale(scale) {
+  return Number.isFinite(scale) && scale > 0 ? scale : 1;
+}
 function resolveDistance(placement, distance, width, height) {
   const maximumDistance = maximumHotspotDistance(width, height);
   if (placement === "surface") {
@@ -2513,6 +2523,7 @@ function HotspotAnchor({
   position,
   width,
   height,
+  scale = 1,
   useAngularScale = true,
   focusContent,
   mode = "billboard",
@@ -2541,7 +2552,15 @@ function HotspotAnchor({
   const normalizedPosition = normalizePanoPosition(position);
   const rendering = internalOrientation && internalPlacement ? { orientation: internalOrientation, placement: internalPlacement } : HOTSPOT_MODE_RENDERING[mode];
   const { orientation: orientation2, placement } = rendering;
-  const resolvedDistance = resolveDistance(placement, distance, width, height);
+  const resolvedScale = resolveScale(scale);
+  const scaledWidth = width * resolvedScale;
+  const scaledHeight = height * resolvedScale;
+  const resolvedDistance = resolveDistance(
+    placement,
+    distance,
+    scaledWidth,
+    scaledHeight
+  );
   const worldPosition = (0, import_react9.useMemo)(
     () => panoPositionToVector3(normalizedPosition, resolvedDistance),
     [normalizedPosition.pitch, normalizedPosition.yaw, resolvedDistance]
@@ -2550,8 +2569,8 @@ function HotspotAnchor({
     () => createSurfaceQuaternion(normalizedPosition),
     [normalizedPosition.pitch, normalizedPosition.yaw]
   );
-  const worldWidth = angularSizeToWorldSize(width, resolvedDistance);
-  const worldHeight = angularSizeToWorldSize(height, resolvedDistance);
+  const worldWidth = angularSizeToWorldSize(scaledWidth, resolvedDistance);
+  const worldHeight = angularSizeToWorldSize(scaledHeight, resolvedDistance);
   const focusGeometry = (0, import_react9.useMemo)(() => {
     const planeGeometry = new import_three9.PlaneGeometry(1, 1);
     const geometry = new import_three9.EdgesGeometry(planeGeometry);