Rotation Configuration Guide¶

Overview¶

You can now control the initial rotation (starting view direction) of 360° images and videos in your config.json. This lets you determine which direction users see when a stage loads.

Configuration¶

Add a rotation property to any image or video stage:

{
  "id": "my-stage",
  "type": "image",
  "url": "...",
  "rotation": {
    "x": 0,
    "y": 1.57,
    "z": 0
  }
}

Rotation Properties¶

Important: For 360° images and videos, only the Y axis (yaw) rotation is applied.

Understanding Y Rotation (Yaw)¶

The Y rotation value is in radians and controls horizontal rotation:

Quick Reference¶

// Common rotations
0       = Facing forward (default)
1.57    = Facing right (90°)
3.14    = Facing backward (180°)
-1.57   = Facing left (-90°)

// Custom angles
π/4     = 45° right (0.785 radians)
π/2     = 90° right (1.57 radians)
3π/4    = 135° right (2.356 radians)
π       = 180° (3.14 radians)

Examples¶

Example 1: Image Facing Right¶

{
  "id": "entrance-view",
  "type": "image",
  "url": "https://storage.googleapis.com/bucket/entrance.jpg",
  "rotation": {
    "x": 0,
    "y": 1.57,
    "z": 0
  }
}

Example 2: Video Facing Backward¶

{
  "id": "dolly-shot",
  "type": "video",
  "url": "https://storage.googleapis.com/bucket/dolly.mp4",
  "autoplay": true,
  "loop": true,
  "rotation": {
    "x": 0,
    "y": 3.14,
    "z": 0
  }
}

Example 3: Image Facing Left¶

{
  "id": "side-view",
  "type": "image",
  "url": "https://storage.googleapis.com/bucket/side.jpg",
  "rotation": {
    "x": 0,
    "y": -1.57,
    "z": 0
  }
}

Example 4: No Rotation (Default)¶

{
  "id": "front-view",
  "type": "image",
  "url": "https://storage.googleapis.com/bucket/front.jpg"
}

Your Mastaba Config Example¶

Here's how you might add rotation to your Mastaba stages:

{
  "experience": {
    "title": "Mastaba VR Experience",
    "description": "Immersive architectural journey"
  },
  "stages": [
    {
      "id": "frame-1-intro-text",
      "type": "image",
      "url": "https://storage.googleapis.com/mastaba-assets/Injected%20Outputs/MSTB_1_INTRO_TEXT.jpg",
      "rotation": {
        "x": 0,
        "y": 0,
        "z": 0
      }
    },
    {
      "id": "frame-2-intro-notext",
      "type": "image",
      "url": "https://storage.googleapis.com/mastaba-assets/Injected%20Outputs/MSTB_2_INTRO_NOTEXT.jpg",
      "rotation": {
        "x": 0,
        "y": 1.57,
        "z": 0
      }
    },
    {
      "id": "frame-3-dolly",
      "type": "video",
      "url": "https://storage.googleapis.com/mastaba-assets/Injected%20Outputs/MSTB_3_Dolly.mp4",
      "autoplay": true,
      "loop": true,
      "rotation": {
        "x": 0,
        "y": 0,
        "z": 0
      }
    }
  ]
}

Converting Degrees to Radians¶

If you prefer working in degrees:

Formula: radians = degrees × (π / 180)

Common conversions: - 45° = 0.785 radians - 90° = 1.57 radians (π/2) - 135° = 2.356 radians - 180° = 3.14 radians (π) - 270° = 4.71 radians (3π/2) - 360° = 6.28 radians (2π)

Online calculator: Just search "degrees to radians" or use JavaScript:

degreesToRadians = degrees * (Math.PI / 180)

Testing Rotation¶

1. Edit config.json and add rotation to a stage
2. Refresh browser to reload config
3. Navigate to that stage
4. Check console - you'll see: Photo dome rotation set to: 1.57 radians
5. View will start at the configured rotation

Tips¶

Finding the Right Rotation¶

1. Start at 0 (default forward)
2. Manually rotate the view (drag mouse) to find desired angle
3. Estimate the rotation (quarter turn = π/2, half turn = π, etc.)
4. Add to config and test
5. Adjust as needed

Common Mistakes¶

❌ Using degrees instead of radians

"rotation": { "y": 90 }  // Wrong! This is 90 radians, not 90°

✅ Use radians

"rotation": { "y": 1.57 }  // Correct! 90° in radians

❌ Trying to rotate X or Z for domes

"rotation": { "x": 1.57 }  // Won't work for domes (only Y axis)

✅ Only use Y rotation for domes

"rotation": { "y": 1.57 }  // Works! Y is horizontal rotation

Advanced: Fine-Tuning¶

For precise control, use decimal values:

{
  "rotation": {
    "x": 0,
    "y": 1.2,
    "z": 0
  }
}

Result: Rotated approximately 68° to the right.

Console Feedback¶

When rotation is applied, you'll see in the console:

Photo dome rotation set to: 1.57 radians

Video dome rotation set to: 3.14 radians

This confirms your rotation is being applied!

User Interaction¶

Important: Users can still freely look around after the initial rotation is applied. The rotation only sets the starting view direction, not a limit on where they can look.

Future Enhancements¶

Planned features: - X and Z rotation support for custom camera angles - Automatic rotation animation on load - Rotation presets in config ("front", "left", "right", "back") - Interactive rotation editor

Quick Start¶

Want to rotate a stage 90° to the right?

Add this to your stage in config.json:

"rotation": { "x": 0, "y": 1.57, "z": 0 }

Want to face backward (180°)?

"rotation": { "x": 0, "y": 3.14, "z": 0 }

Want to face left (90° left)?

"rotation": { "x": 0, "y": -1.57, "z": 0 }

That's it! Refresh and test! 🔄✨