Documentation

Welcome to the Ziric Studios 3D Map Animator documentation. This state-of-the-art tool enables creators, journalists, and developers to generate cinematic map flyovers directly in the browser.

Unlike traditional video editing software that requires massive rendering times and complex plugins, our solution leverages WebGL to render 3D terrain and buildings in real-time, allowing for instant feedback and rapid export.

Getting Started

Prerequisite: You must have a Mapbox Access Token to initialize the map renderer.

1. Obtain a Mapbox Token

Visit Mapbox.com and create a free account.
Navigate to your "Account" dashboard.
Locate the "Default Public Token" section.
Copy these characters starting with pk.eyJ....

2. Launch the Tool

Open the tool by clicking "Open Tool" in the header. Paste your token into the sidebar field labeled "Mapbox Access Token". The tool will remember this for future sessions.

Core Features

Path-Following Camera: The camera doesn't just fly straight; it physically travels along your route, banking and turning like a drone or aircraft.
3D Buildings & Terrain: Utilizing elevation data, mountains look real and city skylines rise from the ground.
Dynamic Lighting: Realistic atmospheric lighting that simulates sun position and sky scattering.
Client-Side Recording: Generate standard MP4/WebM video files without server-side processing queues.

Usage Guide

Step 1: Set Locations

Use the search bars to define your standard point-to-point journey.

Start Location: Where the camera begins (e.g., "Times Square, NY").
Destination: Where the flight ends (e.g., "Central Park, NY").

Step 2: Customization

Tailor the look and feel of your animation:

Duration: Controls the flight speed. 5s is fast (jet-like), 15s is cinematic and slow.
Map Style:
- Satellite Realistic: Best for nature and long distances.
- Cinematic Dark: Best for data visualization and night cities.
- Navigation: High contrast for clear road visibility.

Performance Mode

3D rendering is resource-intensive. If you are experiencing lag, stuttering, or if your browser crashes, enable Performance Mode (Low Lag).

What it changes: Performance Mode disables the 3D terrain mesh (mountains become flat) and the atmospheric sky layer. This significantly reduces GPU load while keeping the core functionality intact.

Exporting Video

Once you are happy with the preview, click the Export MP4 button.

The animation will restart from the beginning.
A recording indicator will appear.
Do not switch tabs during recording to ensure smooth frame capture.
Once finished, a file named map-animation-[timestamp].webm will automatically download.

Note: The file is technically a WebM container. It plays in all modern browsers and players (VLC), and can be converted to MP4 instantly using any converter.

Troubleshooting

Map is black/blank

This usually means your Access Token is invalid or has restricted scopes. Ensure you copied the public token correctly without extra spaces.

Video has no sound

The map animator generates visual video only. You can add music or voiceover in your video editor of choice.

Technical Information

For developers interested in how this works:

Engine: Mapbox GL JS v2.15 (WebGL 2.0 context)
Geospatial Math: Turf.js for great-circle path calculation and bearing interpolation.
Recording: MediaRecorder API capturing a 30fps stream directly from the canvas element.