Hoppa till huvudinnehåll

Asset library

assetsPath points at the separate data-library root, served on assetsPort (normally 3002).

Browse the TellUs data catalogue for thumbnails and IDs. This page explains how to maintain the library.

An asset's catalogue entry, descriptor, and media files must agree:

tellus-data/
index.json
earth/
blue_marble/
asset.json
3840.png
thumbnail.jpg
overlays/
country_borders/
asset.json
4096.png
thumbnail.jpg
local/
school-map/
asset.json
map.png
thumbnail.jpg

The root index​

index.json lists descriptor paths relative to the data root:

[
"earth/blue_marble/asset.json",
"earth/overlays/country_borders/asset.json",
"local/school-map/asset.json"
]

Use forward slashes and list each descriptor once. Unlisted folders are not discovered.

The renderer derives the media directory from the index path. For local/school-map/asset.json, a layer path of map.png is served as /local/school-map/map.png.

The asset descriptor​

For a static base map, adapt this complete example to your actual data and source:

{
"id": "local_school_map",
"name": "School outreach map",
"author": "Your organization",
"version": 1,
"thumbnail": "thumbnail.jpg",
"metadata": {
"source": "Your dataset provider and source reference",
"date": "2025",
"duration": "Static map; no animation",
"visual": "Describe the colors, units, scale, and legend",
"description": "Explain what is shown and what visitors should notice",
"related": ["blue_marble"]
},
"layers": [
{
"kind": "equirect",
"path": "map.png"
}
]
}
FieldMeaning
idUnique, stable identifier used by assistant tools, linked topics, and scene selection. It need not equal the folder name.
nameHuman-readable dataset name.
authorCreator or curator. Required by the current schema.
versionString or number identifying your descriptor revision.
thumbnailOptional image path relative to the descriptor directory.
urlOptional reference/source page URL. Put explanatory source information in metadata too.
metadataRequired object containing explanatory information; additional fields are allowed.
layersArray of media layers. A renderable globe dataset needs an equirect layer.
Layer kindequirect for globe imagery; legend for a legend/information graphic.
Layer pathMedia path relative to the descriptor directory.
Layer overlayOptional layer compositing flag. It does not classify the whole asset as a selectable overlay.
Layer contentOptional textual layer description.

Use globe imagery in an equirectangular projection, normally 2:1. A normal perspective photo will not wrap correctly. For videos, use browser-supported media and rehearse loading/playback on the target globe; time control through the assistant is not implemented for Webrender.

Add a dataset​

  1. Choose a folder under the asset root and copy the map/video plus any thumbnail or legend files into it.
  2. Create asset.json, using an existing working asset of the same type as a starting point.
  3. Give it a unique ID and accurate metadata.
  4. Add its descriptor path to the root index.json.
  5. Check the descriptor and layer URLs in a browser on the operator device.
  6. Restart the app or reload the globe renderer during maintenance to refresh its cached catalogue.
  7. Select the new base asset from Webrender → Assets, then test an assistant request and any linked topic.

For the sample above, test http://pufferfish:3002/local/school-map/asset.json and http://pufferfish:3002/local/school-map/map.png. Substitute your host and port.

Refreshing only the tablet/frontend may leave the globe catalogue unchanged.

Reorganize folders​

Choose your own hierarchy for base assets. Move the descriptor and media together and update index.json; relative media paths can then stay the same.

Keep IDs stable to preserve quick-topic links, prompts, related metadata, and renderer presets.

Overlay folder convention

Keep selectable overlays under earth/overlays/; that path is how the renderer recognizes them. An overlay name, ID prefix, or layer flag does not replace this convention.

Use transparency for overlay images and compatible Earth base maps. Borders, city names, and other Earth overlays will not align meaningfully on Mars or another body.

Remove a dataset​

Remove its descriptor path from index.json first. Remove or update topic links, scenario instructions, related metadata, and saved presets that reference it. Reload/restart the renderer and confirm a remaining asset still works.

You can leave the unlisted folder on disk as an archive, or remove it after backing it up. Deleting only the folder while leaving the index entry creates a broken catalogue reference.

Write useful metadata​

The scene service exposes asset.metadata as node properties, which the assistant can retrieve with getNode. A top-level url is not automatically included in those node properties; repeat the relevant source citation in metadata.source.

Provide:

  • What the dataset actually represents, and whether it is observed, modeled, or illustrative.
  • Source/organization, reference URL, publication date, and data time coverage.
  • Units, scale, color/legend meanings, and animation duration or frame timing.
  • Important limitations: gaps, aggregation, historical coverage, or projections.
  • Useful related asset IDs.

Some descriptors have empty source/date/description fields. Empty does not mean current or complete. Include legend meaning in text metadata; getNode does not interpret the legend image.

A scenario rule can ask the assistant to retrieve this information whenever a dataset loads. Check its explanation against the actual metadata.

If loading fails, see asset troubleshooting.