Documentation

Démarrer en 10 lignes

Une feuille de style + un script chargé en <script>, un <div> et un appel init :

<link  rel="stylesheet" href="https://static.dioramap.com/sdk/v0.8.1/dioramap-viewer.css">
<script src="https://static.dioramap.com/sdk/v0.8.1/dioramap-viewer.umd.js"></script>

<div id="viewer" style="width:100%;height:600px"></div>
<script>
  DioramapViewer.init({
    apiKey: 'pk_live_…',
    container: document.getElementById('viewer'),
    lat: 48.8584, lon: 2.2945,
  });
</script>

Pour un parcours en deux temps (l'utilisateur choisit d'abord un point sur une carte, puis la scène 3D s'y monte), ajoutez aussi dioramap-location-picker.css + dioramap-location-picker.umd.js et suivez le pattern à trois étapes ci-dessous.

Sécurité & thème

Depuis la version 0.8.0 les deux SDKs livrent leur CSS dans une feuille de style externe (<link>) et n'injectent plus aucune balise <style> au runtime. Vous pouvez donc :

• durcir votre CSP en supprimant 'unsafe-inline' de script-src et style-src : voir la directive type côté viewer et côté picker ;
• thématiser les couleurs et le rayon des coins en surchargeant des variables CSS (--dioramap-* pour le viewer, --dioramap-picker-* pour le picker) depuis votre propre feuille de style chargée après les nôtres.

Obtenir une clé d'API

Créez un compte sur app.dioramap.com, puis générez une clé dans Espace client → Clés. Chaque clé est associée à une liste d'origines autorisées (les domaines depuis lesquels la clé peut s'utiliser). Pour le développement local, ajoutez http://localhost:{port} ou similaire à la liste.

Référence API

Cas d'utilisation classique — 3 étapes

L'utilisateur choisit un point sur la carte, la scène 3D s'y monte, puis il pose un produit (abri, piscine, panneau solaire…) qui suit le curseur et qu'il peut déplacer ou orienter. Tout se déroule dans un même conteneur.

Étape 1 — Le picker prend le conteneur

// Au boot de la page.
let viewer = null;
let picker = await DioramapLocationPicker.init({
  container: '#stage',
  radius: 75,
  onConfirm: ({ lat, lon }) => {
    picker.dispose();          // libère MapLibre
    picker = null;
    startViewer(lat, lon);
  },
});

Étape 2 — Le viewer remplace le picker dans le même conteneur

async function startViewer(lat, lon) {
  viewer = await DioramapViewer.init({
    container: '#stage',
    apiKey: 'pk_live_…',
    lat, lon, radius: 75,
    onError: (err) => console.error('viewer error:', err),
  });
  enablePlaceButtons(true);           // active la barre produits
}

Étape 3 — Bouton « Placer » par produit

async function placeProduct(product) {
  if (!viewer) return;
  // Fantôme translucide qui suit le curseur ; clic = pose, Échap = annule.
  const uuid = await viewer.startGhostPlace({
    url: product.glb_url,
    label: product.name,
  });
  if (!uuid) return;           // utilisateur a annulé
  // uuid disponible — l'utilisateur peut maintenant déplacer/orienter
  // le modèle au gizmo. Suivez onModelMoved pour persister la position.
}

Notes pratiques

• Gardez les boutons « Placer » désactivés tant que viewer n'est pas résolu — l'utilisateur ne peut rien poser dans une scène pas encore montée.
• Vérifiez les bundles à l'init : si window.DioramapViewer?.init ou window.DioramapLocationPicker?.init est absent, c'est un échec de chargement réseau ou de CSP — affichez un message clair plutôt que de planter silencieusement.
• Persistez les positions de modèles via onModelMoved si vous voulez retrouver la scène à la prochaine visite. Dioramap ne stocke rien côté serveur ; la persistance reste votre responsabilité.
• Une seule scène à la fois par conteneur : avant de remonter le viewer ailleurs, appelez viewer.dispose() pour libérer la mémoire WebGL et fermer la WebSocket.

Une question hors documentation ?

Écrivez à contact@dioramap.com.