Tools for viewing HERE XYZ Studio visualizations in Tangram. This repo contains three distinct pieces of functionality:

• xyz-to-tangram (lib/): module to convert XYZ Studio JSON definitions into Tangram scene definitions, can be run either in browser or node.js.
• Web viewer demo (viewer.js|css): browser-based demo of the converter, with styling and UX patterned off of the official XYZ Studio Viewer.
• Server endpoint demo (server/): server-based demo of the converter, providing an http endpoint to return Tangram scene objects.

Example:

• In XYZ renderer: https://xyz.here.com/viewer/?project_id=33c236e0-d0ef-4338-b0e0-5de3b97f4c0c
• In Tangram: https://xyz-to-tangram.netlify.com/?project_id=33c236e0-d0ef-4338-b0e0-5de3b97f4c0c

All three components are automatically deployed to Netlify when this repo is updated. The npm run build command builds both the library and demos (see details below).

This is the core functionality of this repo. It takes JSON files generated by Studio (available at https://xyz.api.here.com/project-api/projects/${xyzProjectId}), which store the representation of your Studio visualization, and builds a Tangram scene object to faithfully render it.

The module exports a single function, which is designed to be isomorphic (can be executed either in a web browser or node.js server).

Basic usage:

import xyzToTangram from './xyz-to-tangram';
const xyzStyleURL = 'https://xyz.api.here.com/project-api/projects/33c236e0-d0ef-4338-b0e0-5de3b97f4c0c';
const xyzStyle = await fetch(xyzStyleURL).then(r => r.json());
const { scene, legends } = xyzToTangram(xyzStyle);

scene is an Tangram scene object (containing styles, layers, etc.) you can pass directly to Tangram, e.g.:

const layer = Tangram.leafletLayer({ scene });

legends is an array of objects containing information necessary for rendering legends similar to those in the XYZ Studio Viewer, e.g.:

[
  {
    "geomType": "Line",
    "name": "Bus",
    "style": {
      "type": "Line",
      "stroke": "rgba(227,158,60,1)",
      "zIndex": 11,
      "opacity": 1,
      "strokeWidth": 2,
      "strokeLinecap": "round",
      "strokeLinejoin": "miter",
      "strokeDasharray": [0, 0]
    }
  },
  ...
]

xyzToTangram(xyzStyle, options) usage:

• xyzStyle: an XYZ Studio JSON object (must be already loaded, core module doesn't do any networking)
• options:
  • basemap: name of XYZ basemap to use (defined in lib/basemaps.js), e.g. basemap: 'refill'
  • collide: whether labels from XYZ Studio layers should collide with basemap layers (true|false, default true)
  • labelsOnTop: whether basemap labels are shown above XYZ Studio layers (true|false, default true)
  • setStartPosition: whether the Tangram scene camera should be set to load at the XYZ Studio start position (true|false, default true)

You can build the module from scratch with:

npm install
npm run build-lib

This outputs the compiled module to dist/xyz-to-tangram.js.

During development, run npm start, which will compile and start a local server on port 7000, along with a watcher process that automatically rebuilds whenever source files change.

The browser-based demo in viewer.js shows the conversion module used to re-create the styling and interaction of the XYZ Studio Viewer. It does the following:

• Accepts query parameters for: project_id, collide, labelsOnTop.
• Fetches the XYZ Studio JSON over the network according to project id.
• Calls xyzToTangram() to create a Tangram scene object.
• Creates a Leaflet map and loads the Tangram scene.
• Adds interaction hooks for hover/click events to display XYZ Studio cards.
• Displays any legends in the sidebar.

The web demo doesn't have a build/bundling process.

The server demo in server/ shows how the conversion module can be called in a node.js environment. While browser usage creates an "ephemeral" Tangram scene, a server endpoint is useful for cases where you want a persistent http link, such as when loading a converted scene in Tangram Play. It does the following:

• Accepts query parameters for: project_id, collide, labelsOnTop, and format.
  • format can be set to yaml to get YAML-formatted output (using js-yaml).
• Fetches the XYZ Studio JSON over the network according to project id.
• Calls xyzToTangram() to create a Tangram scene object.
• Formats the output as JSON or YAML.

The server demo is writte in the style of an AWS Lambda function, and is deployed on Netlify, using their Functions (serverless) product. The Netlify function is configured in the netlify.toml file, and npm run build-lambda command will package the function for deployment to Netlify.

The same code (in some cases with minor modifications) could be deployed to other serverless contexts (AWS itself) or as a traditional server app with Express (a few more modifications).

Example of using this endpoint to convert and load an XYZ Studio visualization in Tangram Play:

https://play.tangram.city/?scene=https%3A%2F%2Fxyz-to-tangram.netlify.com%2Fconvert%3Fproject_id%3D33c236e0-d0ef-4338-b0e0-5de3b97f4c0c%26format%3Dyaml