JSON Data Format

DataReels Animator uses a simple JSON structure with two main sections:sceneSettings for global configuration and data for your visualization data.

{
  "sceneSettings": {
    "heightScale": 0.8
  },
  "data": [
    {
      "name": "Data Point 1",
      "value": 25.5,
      "rank": 1,
      "description": "Optional description",
      "color": "#FF6B6B",
      "columnColor": "#8B2635",
      "primitiveScale": 1.0,
      "modelPath": null,
      "labelStyle": {
        "borderColor": "rgba(255, 107, 107, 0.7)",
        "title": { "color": "#FF6B6B" }
      }
    }
  ]
}

Scene Settings

The sceneSettings object controls global scene properties.

Property	Type	Default	Description
`heightScale`	Number	0.8	Multiplier for bar heights in the scene

Data Objects

Each object in the data array represents a single data point in your visualization.

Property	Type	Required	Description
`name`	String	✅ Yes	Main title displayed on the label
`value`	Number	✅ Yes	Numerical value determining bar height
`rank`	Number	❌ No	Rank number displayed on label
`description`	String	❌ No	Subtitle displayed below the name
`color`	String	❌ No	Hex color of the 3D primitive on top
`columnColor`	String	❌ No	Hex color of the main bar column
`primitiveScale`	Number	❌ No	Scale multiplier for the 3D primitive
`modelPath`	String	❌ No	Path to custom 3D model (future feature)
`labelStyle`	Object	❌ No	Custom styling for this data point's label

Custom Label Styling

The labelStyle object allows you to customize the appearance of individual data point labels.

"labelStyle": {
  "borderColor": "rgba(255, 107, 107, 0.7)",
  "title": {
    "font": "bold 44px -apple-system, sans-serif",
    "color": "rgba(255, 255, 255, 0.9)"
  },
  "description": {
    "font": "30px -apple-system, sans-serif",
    "color": "rgba(255, 255, 255, 0.6)"
  },
  "value": {
    "font": "bold 96px -apple-system, sans-serif",
    "color": "#00ffff"
  },
  "rank": {
    "font": "36px -apple-system, sans-serif",
    "color": "rgba(255, 255, 255, 0.5)"
  }
}

Label Style Properties

borderColor: RGBA color for the label border and glow effect
title: Styling for the main name text
description: Styling for the description text
value: Styling for the numerical value
rank: Styling for the rank number

Complete Examples

Simple Data Visualization

{
  "sceneSettings": { "heightScale": 0.8 },
  "data": [
    {
      "name": "Product A",
      "value": 150,
      "rank": 1,
      "description": "Top seller",
      "color": "#4CAF50",
      "columnColor": "#2E7D32"
    },
    {
      "name": "Product B",
      "value": 120,
      "rank": 2,
      "description": "Second place",
      "color": "#2196F3",
      "columnColor": "#1565C0"
    }
  ]
}

Advanced with Custom Styling

{
  "sceneSettings": { "heightScale": 1.2 },
  "data": [
    {
      "name": "Champion",
      "value": 250,
      "rank": 1,
      "description": "Gold Medal",
      "color": "#FFD700",
      "columnColor": "#B8860B",
      "primitiveScale": 1.5,
      "labelStyle": {
        "borderColor": "rgba(255, 215, 0, 0.8)",
        "title": {
          "color": "#FFD700",
          "font": "bold 48px -apple-system, sans-serif"
        },
        "value": {
          "color": "#FFD700",
          "font": "bold 120px -apple-system, sans-serif"
        }
      }
    }
  ]
}

JavaScript API Reference

When using DataReels Animator programmatically, these are the key functions available:

Core Functions

buildSceneFromData(jsonData)

Builds the 3D scene from your JSON data structure.

startTour(callback)

Starts the cinematic camera tour with optional completion callback.

startRecording(aspectRatio, filename)

Records the tour as a video file with specified aspect ratio.

stopTour()

Stops the current tour or recording.

Best Practices

✅ Do

• Use meaningful names for your data points
• Keep descriptions concise (2-3 words)
• Use contrasting colors for visibility
• Limit data points to 15 or fewer for best performance
• Test different height scales for optimal viewing
• Use consistent color schemes

❌ Don't

• Use very similar colors that are hard to distinguish
• Make descriptions too long (they may be cut off)
• Use negative values (not currently supported)
• Include more than 20 data points
• Use extreme primitive scales (<0.1 or >3.0)
• Forget to test on different screen sizes

Troubleshooting

Common Issues

JSON file won't upload

Ensure your JSON is valid. Use a JSON validator tool and check for missing commas, brackets, or quotes. Common issues include trailing commas and unescaped quotes in strings.

Bars are too tall or too short

Adjust the heightScale value in sceneSettings. Values between 0.3 and 1.5 work best for most datasets.

Labels are hard to read

Use high contrast colors and ensure your borderColor is visible against the scene background. Consider using custom labelStyle properties.

Recording fails or produces corrupted video

Keep the browser tab active during recording. Close other intensive applications and ensure your browser supports the MediaRecorder API (Chrome/Firefox recommended).

Documentation

Table of Contents