README.md

Dotty Globe

A simple and interactive 3D globe visualization using ThreeJS. Perfect for displaying data points dynamically on a rotating globe.

The globe uses a 3D point cloud to draw the continents and dynamic spikes to visualize varying data intensities on the globe's surface. You can also visualize connections between different locations using arcs (paths) and interact with the globe through onClick and onHover event handlers.

Quick start

To install the dotty-globe package:

npm install dotty-globe

Create a container for the globe in your HTML:

<div id="globe-container" style="width: 500px; height: 500px;"></div>

Initialize the container with JavaScript:

const container = document.getElementById("globe-container")
createGlobe({ container })

Usage Example

To update the points on the globe dynamically, you can use the following example in a React component:

import { useEffect, useRef, useState } from "react"
import { createGlobe } from "dotty-globe"

export default function Home() {
  const containerRef = useRef(null)
  const globeRef = useRef(null)
  const [dataPoints, setDataPoints] = useState([])

  useEffect(() => {
    if (containerRef.current) {
      globeRef.current = createGlobe(containerRef.current, dataPoints)
    }
  }, [])

  useEffect(() => {
    const interval = setInterval(() => {
      const newPoint = {
        label: `Random Point`,
        key: `key-${Math.random()}`,
        metadata: {},
        coordinate: [
          parseFloat((Math.random() * 180 - 90).toFixed(4)),
          parseFloat((Math.random() * 360 - 180).toFixed(4)),
        ],
        intensity: Math.random().toFixed(2),
      }
      setDataPoints((prevPoints) => {
        const updatedPoints = [...prevPoints, newPoint]
        return updatedPoints.length > 15
          ? updatedPoints.slice(1)
          : updatedPoints
      })
    }, 100)

    return () => clearInterval(interval)
  }, [])

  useEffect(() => {
    if (globeRef.current) {
      globeRef.current.update(dataPoints)
    }
  }, [dataPoints])

  return (
    <main>
      <div className="flex justify-center">
        <div
          id="globe-container"
          style={{
            height: "500px",
            width: "500px",
          }}
          ref={containerRef}
        ></div>
      </div>
    </main>
  )
}

Paths

You can visualize connections between different coordinates using paths. Each path object should include from and to coordinates in the format [latitude, longitude]. Here’s an example:

Copy code
const paths = [
  { from: [37.7749, -122.4194], to: [40.7128, -74.006] },
  { from: [40.7128, -74.006], to: [51.5074, -0.1278] },
  // More paths...
]

createGlobe({
  container: container,
  dataPoints: dataPoints,
  paths: paths,
})

Event Handlers: onClick, onHover and onHoverOut

You can also add interactivity to the globe by using event handlers. These functions receive the data of the point that was clicked or hovered over. Here’s how to use them:

const onClick = (data) => {
  console.log("Clicked on: ", data)
}

const onHover = (data) => {
  console.log("Hovered over: ", data)
}

const onHoverOut = (data) => {
  console.log("Hovered out: ", data)
}

createGlobe({
  container: container,
  dataPoints: dataPoints,
  paths: paths,
  onClick,
  onHover,
  onHoverOut,
})

In this example, when a user clicks, hovers on, or leaves a point on the globe, the event handlers are triggered and log the data of the point. You can use this functionality to add more complex interactions such as showing tooltips, highlighting specific points, or triggering other visual effects.

Develop

To start developing with the dotty-globe package, clone the repository and install the dependencies:

git checkout https://github.com/blairjordan/dotty-globe
npm install
npm run dev

This will start a development server that you can use to see your changes live.

Build

To build the project for production, run:

npm run build

This will create an optimized build of the project in the dist directory.

Contributing

If you would like to contribute to the project, please follow these steps:

1. Fork the repository.
2. Create a new branch with a descriptive name (git checkout -b feat/new-feature).
3. Commit your changes (git commit -am 'feat: add some feature').
4. Push to the branch (git push origin feat/new-feature).
5. Create a new Pull Request.