Getting Started

Installation

Prerequisites

• Node.js version 18 and above.

three-auto can be installed using the following methods:

npm

$ npm add -D three-auto

pnpm

$ pnpm add -D three-auto

yarn

$ yarn add -D three-auto

Note

three-auto is an ESM-only package. Do not use require() to import it, and make sure your latest package.json contains "type": "module".

three.js as peer dependency

If you want to use three.js components or APIs for custom development, you should also explicitly install three as a dependency. If your project uses typescript, you should also install @types/three.

Import into Project

First, when you want to create an auto-three instance, you need a canvas DOM root node or a virtual DOM node (supported by frameworks like Vue and React) to render the Three.js scene.

• index.html

<div style="width:100%;height:600px;position:relative">
  <canvas id="_scene" />
</div>
<script type="module" src="./main.ts"></script>

Note

Please give the canvas or the canvas's parent container a width and height so that the scene can be displayed.

• main.ts

import * as AUTO from "three-auto";
import * as THREE from "three";

const instance = new AUTO.ThreeAuto();
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshBasicMaterial({
  color: "#E89ABE",
  transparent: true,
});
const box = new THREE.Mesh(geometry, material);

instance.scene.add(box);

instance.time.on("tick", () => {
  box.rotation.y = instance.time.elapsedTime;
});

Note

By default, if the canvas container id is _scene, we don't need to manually get the DOM element.

You should see a pink cube rotating in the center of the screen!

Chart Mode

Above we introduced how to import three-auto into your project, but obviously this is not enough. Let's see how to render a 3D map!

Note

import ZheJiangCity from '../public/ZheJiangCity.json'

First you need to create a geographic JSON file.

China Map JSON Files

World Map JSON Files

• main.ts

import * as AUTO from "three-auto";
import ZheJiangCity from '../public/ZheJiangCity.json'

// Specify chart configuration options and data
const instance = new AUTO.ThreeAuto(undefined, {
  id: "_scene",
  name: "Hello three auto",
  camera: {
    type: 'PerspectiveCamera',
    fov: 75,
    near: 0.1,
    far: 1000,
    position: {
      x: 0,
      y: 0,
      z: 20,
    },
    lookAt: true,
    controls: {
      enable: true,
      enableDamping: true,
      enablePan: true,
    },
  },
  size: {
    type: "window",
    id: "",
  },
  renderer: {
    antialias: true,
    alpha: true,
    clearAlpha: 1,
    clearColor: '#000000',
  },
  series: [
    {
      name: "Outline Map",
      id: 0,
      type: "map",
      json: ZheJiangCity,
      itemStyle: {
        depth: 1,
        bevelEnabled: false,
        bevelSegments: 1,
        bevelSize: 0,
        bevelThickness: 0,
        extrudeFaces: {
          material: 'MeshNormalMaterial',
          color: "#ccc",
          opacity: 1,
          metalness: 1,
          roughness: 1,
        },
        crossSection: {
          material: 'MeshNormalMaterial',
          opacity: 0.8,
          color: "#000",
        },
        lineStyle: {
          show: true,
          color: "#A0E5FF",
          width: 2,
        },
        label: {
          show: true,
          distance: 1.3,
          rotation: {
            x: 0,
            y: 0,
            z: 0,
          },
          textStyle: {
            padding: '8px',
            'font-size': '20px',
            color: "#fff",
            bold: true,
            'font-weight': 400,
            'font-style': 'normal',
          },
        },
      },
    },

});

// Print three-auto instance
console.log(instance)

Note

Now your first map chart is born!