TrackDraw Viewer

Embed interactive 2D and 3D FPV race tracks in your website or application. @trackdraw/viewer renders portable TrackDraw track designs in a read-only viewer, with a plain JavaScript API and support for offline track archives.

• 2D and 3D views with per-instance themes, measurement units, labels, and obstacle numbering.
• Portable track data with validation and renderer compatibility checks.
• Offline viewing from .tdviewer.zip archives containing a track and its catalog textures.
• Self-contained integration with scoped styles and no TrackDraw account or editor state required.

Installation

For an application with a JavaScript bundler:

npm install @trackdraw/viewer

No separate React installation is needed. Import the viewer stylesheet once; no Tailwind configuration is required in the host application.

For a site without a bundler, use the plain HTML integration.

Quick start

The default API bundles its own rendering runtime. Your application does not need React. mountTrack loads and validates snapshot JSON or an offline archive, checks renderer compatibility and manages archive textures. Catch loading errors in your page; use an AbortSignal when your component can unmount during loading. See the integration guide for cleanup and error handling. This API follows the development source and will be available in the next package release.

import { mountTrack } from "@trackdraw/viewer";
import "@trackdraw/viewer/static/trackdraw-viewer.css";

// #track is an existing element, e.g. <div id="track" style="height: 420px"></div>.
const viewer = await mountTrack("#track", {
  source: "/track.snapshot.json", // A public snapshot URL, .tdviewer.zip URL or File.
  initialView: "3d",
});

viewer.update({ theme: "dark" }); // Other options and the track are preserved.
await viewer.setSource("/final.snapshot.json"); // Validated before replacing the track.
viewer.destroy(); // Unmount and release archive textures when removing the embed.

Plain HTML

Copy dist/static/trackdraw-viewer.global.js and dist/static/trackdraw-viewer.css from the installed package to your site's public files. The JavaScript bundle includes React and its other JavaScript dependencies.

<link rel="stylesheet" href="/vendor/trackdraw-viewer.css" />
<div id="track" style="height: 420px; width: 100%"></div>
<script src="/vendor/trackdraw-viewer.global.js"></script>
<script>
  // Provide a validated, compatible viewer snapshot from your application.
  const viewer = TrackDrawViewer.createTrackDrawViewer(
    document.getElementById("track"),
    { design: snapshot.design, theme: "light" }
  );
  window.addEventListener("pagehide", () => viewer.destroy());
</script>

See the complete HTML example for archive upload, validation, error handling, and cleanup.

Track data

A viewer snapshot contains the track geometry, display metadata, required renderer capabilities, and an asset manifest. It does not require editor storage, inventory, ownership, or account data.

For imported JSON, use validateViewerDesignSnapshot from @trackdraw/viewer/snapshot/schema, then check isViewerCompatible from @trackdraw/viewer/snapshot/version before rendering. Validation and renderer compatibility are separate checks.

For TrackDraw REST API responses, pass response.data through viewerSnapshotFromApi from @trackdraw/viewer/snapshot/api. Raw API shapes use a different format and should not be passed directly to the viewer.

The integration guide includes a validation example, mount options, external 2D/3D controls, and archive creation.

Offline viewing and assets

A .tdviewer.zip archive carries snapshot.json and the catalog textures used by that track. Load it with readViewerArchive, then use createViewerArchiveAssets to provide an assetResolver to the viewer. Dispose of the asset URLs after destroying the viewer. The integration guide includes a complete example.

Install the viewer JavaScript and CSS locally for offline use; archives contain data and images, not executable code. User-uploaded imagery and maps are outside the current archive format.

Online catalog textures load from https://assets.trackdraw.app by default. Set assetsBaseUrl or assetResolver to use your own local assets; assetResolver takes precedence. Third-party catalog textures are not bundled in the npm package. The TrackDraw watermark is embedded and requires no network request.

Browser support

Use a modern browser with ES modules, ResizeObserver, and CSS nesting support. The 3D view requires WebGL2; the 2D view remains available when WebGL2 is unavailable or 3D initialization fails.

Each viewer owns its theme and viewport. Styles are scoped to the viewer, and the package does not install account calls, analytics, or persistent browser storage. A 2D-only viewer does not mount a WebGL renderer or load 3D textures.

Development and support

See Contributing for local setup, validation commands, and dependency maintenance, and Publishing for the release workflow.

Report bugs or request features in GitHub Issues. For rendering problems, include the viewer version, browser, and a minimal track that reproduces the issue.

License

Apache-2.0. See NOTICE.md for attribution and third-party asset information.

Shared schema

This repository contains two npm workspaces: packages/schema publishes @trackdraw/schema for portable snapshot types, validation, identity, archives and asset helpers; packages/viewer publishes @trackdraw/viewer for rendering. Data producers can use schema without installing a renderer. Existing viewer data subpaths remain available through viewer 1.x; see Shared schema migration. Both packages share a release version, with schema published first.

Transparent 3D presentation

Mount a floating, interactive course directly on a light or dark host background:

import { createTrackDrawViewer } from "@trackdraw/viewer";
import "@trackdraw/viewer/static/trackdraw-viewer.css";

const viewer = createTrackDrawViewer(document.querySelector("#course"), {
  design: snapshot.design,
  presentation: "transparent",
});
// Give #course a height (for example 420px). Optional host-owned reset button:
document.querySelector("#reset").onclick = () => viewer.resetOverview();

presentation defaults to "framed", preserving existing 2D/3D embeds. "transparent" defaults to 3D, hides the toolbar and axes, and shows a minimal accessible Reset overview button. Override showViewControls, show3DAxes, and showResetControl independently; use showResetControl: false when supplying host controls. Host framing remains host-owned. The viewer's styles remain scoped to .trackdraw-viewer.

The alpha-transparent WebGL canvas retains the bounded field plate, obstacles, textures and racing line, without sky, fog or surrounding terrain. Its canonical 46° perspective overview uses direction [-14, 18, 20] and 15% padding, matching TrackDraw's transparent PNG export. Actual scene bounds (including obstacle height) and the container aspect ratio determine target and distance. Loading geometry, design updates, resizing and resetOverview() refit the course. Orbit and zoom remain interactive on desktop and touch. The canonical preset takes precedence over camera3D in this mode.

If WebGL is unavailable or fails, the viewer displays the existing 2D fallback with an accessible explanation. onViewStateChange reports the effective view for host controls. Loading, fallback and reset copy can be customized through labels.loading3D, labels.unavailable3D, and labels.resetOverview. A fallback is a normal 2D canvas, rather than a transparent 3D scene.