@goldlabelapps/gpxroute

Official embeddable 3D Cesium venue and route viewer component for GpxRoute° and Skiddle venues.

Designed for high performance, zero client bundle bloat, and strict intellectual property protection.

Intellectual Property Protection & Architecture

Because this package is distributed publicly on npm, it is engineered to protect GpxRoute proprietary algorithms, 3D assets, and geospatial IP:

• 🔒 Zero IP Leakage: All proprietary 3D Cesium rendering, terrain DEM tilesets, photorealistic meshes, camera flight splines, and GIS algorithms run remotely on the hosted GpxRoute infrastructure.
• ⚡ Ultra Lightweight Bundle: No massive CesiumJS dependencies, WebGL shaders, or WASM binaries shipped to your client application.
• 🛡️ Zero Token Exposure: Sensitive Cesium ion tokens, Google Photorealistic 3D Tiles credentials, and private GIS keys remain completely protected on the server.

Primary Component: SkiddleVenue

The primary component exposed by this package is <SkiddleVenue />. It accepts a Skiddle venue data object, smoothly flies the 3D camera to the venue's latitude and longitude, and begins an animated 360-degree orbit around the venue location.

Venue Data Schema

{
  "id": "38952",
  "name": "Hare And Hounds Kings Heath",
  "address": "106 High Street, Kings Heath",
  "town": "Birmingham",
  "postcode": "B14 7JZ",
  "countrycode": "GB",
  "cityname": "Birmingham",
  "phone": "0121 444 2081",
  "latitude": "52.43462200",
  "longitude": "-1.89298000",
  "link": "https://www.skiddle.com/whats-on/Birmingham/Hare-And-Hounds-Kings-Heath/"
}

Installation

pnpm add @goldlabelapps/gpxroute
# or
npm install @goldlabelapps/gpxroute

React / Next.js Usage

1. Basic Embed

"use client";

import { SkiddleVenue, type SkiddleVenueData } from "@goldlabelapps/gpxroute";

const venue: SkiddleVenueData = {
  id: "38952",
  name: "Hare And Hounds Kings Heath",
  address: "106 High Street, Kings Heath",
  town: "Birmingham",
  postcode: "B14 7JZ",
  countrycode: "GB",
  cityname: "Birmingham",
  phone: "0121 444 2081",
  latitude: "52.43462200",
  longitude: "-1.89298000",
  link: "https://www.skiddle.com/whats-on/Birmingham/Hare-And-Hounds-Kings-Heath/",
};

export function Venue3DPreview() {
  return (
    <div style={{ width: "100%", maxWidth: "800px", height: "500px" }}>
      <SkiddleVenue
        venue={venue}
        autoPlay={true}
        theme="dark"
        borderRadius="16px"
        onReady={() => console.log("3D Cesium venue loaded")}
      />
    </div>
  );
}

2. Programmatic Playback & Orbit Control via Ref

"use client";

import React, { useRef } from "react";
import { SkiddleVenue, type SkiddleVenueHandle, type SkiddleVenueData } from "@goldlabelapps/gpxroute";

export function ControlledVenueViewer({ venue }: { venue: SkiddleVenueData }) {
  const viewerRef = useRef<SkiddleVenueHandle>(null);

  return (
    <div className="space-y-4">
      <SkiddleVenue
        ref={viewerRef}
        venue={venue}
        height="500px"
        onProgress={(pct) => console.log(`Orbit progress: ${(pct * 100).toFixed(0)}%`)}
      />

      <div className="flex gap-2">
        <button onClick={() => viewerRef.current?.play()}>Resume Orbit</button>
        <button onClick={() => viewerRef.current?.pause()}>Pause Orbit</button>
        <button onClick={() => viewerRef.current?.seek(0)}>Reset Orbit</button>
      </div>
    </div>
  );
}

Web Component Usage (Vanilla HTML / CMS)

The package automatically provides and registers the <skiddle-venue> Custom Element for non-React environments:

<script type="module" src="https://cdn.jsdelivr.net/npm/@goldlabelapps/gpxroute/dist/index.js"></script>

<skiddle-venue
  name="Hare And Hounds Kings Heath"
  latitude="52.43462200"
  longitude="-1.89298000"
  address="106 High Street, Kings Heath"
  town="Birmingham"
  postcode="B14 7JZ"
  theme="dark"
  border-radius="16px"
  height="500px"
></skiddle-venue>

<script>
  const el = document.querySelector("skiddle-venue");
  el.addEventListener("ready", () => console.log("Venue loaded!"));
  el.addEventListener("progress", (e) => console.log("Orbit progress:", e.detail.progress));
</script>

Props Reference

| Property / Attribute | Type | Default | Description | | :--- | :--- | :--- | :--- | | venue | SkiddleVenueData (required) | — | Skiddle venue object containing name, latitude, longitude, etc. | | host | string | "https://gpxroute.pro" | Hosted 3D terrain service origin. | | width | string \| number | "100%" | Container width (e.g. 800 or "100%"). | | height | string \| number | "500px" | Container height (e.g. 500 or "500px"). | | aspectRatio | string | undefined | Optional CSS aspect ratio (e.g. "16/9"). | | autoPlay | boolean | true | Automatically begin the camera flight and 360 orbit when loaded. | | theme | "dark" \| "light" | "dark" | Color palette for overlays and controls. | | borderRadius | string \| number | "16px" | Corner radius for the viewer viewport. | | allowFullscreen | boolean | true | Allows browser fullscreen expansion. | | title | string | "Skiddle Venue: [name]" | Accessibility title for the iframe. | | onReady | () => void | — | Fired when the 3D Cesium scene completes initial load. | | onPlay | () => void | — | Fired when the camera orbit starts. | | onPause | () => void | — | Fired when the camera orbit is paused. | | onProgress | (progress: number) => void | — | Fired with normalized orbit cycle progress (0.0 - 1.0). | | onError | (error: string) => void | — | Fired if a scene loading error occurs. |

Development & Testing

# Build the package
pnpm --filter @goldlabelapps/gpxroute run build

# Run unit tests
pnpm --filter @goldlabelapps/gpxroute run test

# Type check
pnpm --filter @goldlabelapps/gpxroute run type-check

License

MIT © Goldlabel Apps