@plexus/earth

Primitive-based Earth visualization component for React Three Fiber. Build stunning 3D Earth visualizations with composable primitives.

Installation

npm install @plexus/earth

Peer Dependencies

npm install @react-three/fiber @react-three/drei react react-dom three

Quick Start

import { Earth } from '@plexus/earth';

function App() {
  return (
    <Earth
      dayMapUrl="/textures/earth-day.jpg"
      cloudsMapUrl="/textures/earth-clouds.jpg"
      enableRotation={true}
    />
  );
}

API

Earth (Composed Component)

The main pre-configured component with sensible defaults.

Props:

• dayMapUrl?: string - Earth day texture (default: /day.jpg)
• bumpMapUrl?: string - Bump map for surface detail (default: /bump.jpg)
• cloudsMapUrl?: string - Cloud layer texture (default: /clouds.jpg)
• normalMapUrl?: string - Normal map for advanced lighting
• brightness?: number - Overall scene brightness (default: 1.2)
• enableRotation?: boolean - Auto-rotate the Earth (default: false)
• cameraPosition?: [number, number, number] - Camera position (default: [0, 0, 15000])
• cameraFov?: number - Camera field of view (default: 45)
• minDistance?: number - Min zoom distance (default: 7000)
• maxDistance?: number - Max zoom distance (default: 50000)
• children?: React.ReactNode - Custom content to render in the scene

Example:

<Earth
  dayMapUrl="/earth.jpg"
  enableRotation={true}
  brightness={1.5}
  cameraPosition={[0, 0, 20000]}
/>

EarthScene (Scene Primitive)

Canvas with lights and controls - use when you want to customize what's rendered.

Props:

• cameraPosition?: [number, number, number]
• cameraFov?: number
• minDistance?: number
• maxDistance?: number
• brightness?: number
• children?: React.ReactNode

Example:

import { EarthScene, EarthSphereRoot } from '@plexus/earth';

function CustomEarth() {
  return (
    <EarthScene brightness={1.5}>
      <EarthSphereRoot textureUrl="/custom.jpg" />
      {/* Add satellites, markers, etc. */}
      <mesh position={[8000, 0, 0]}>
        <sphereGeometry args={[200, 32, 32]} />
        <meshStandardMaterial color="red" />
      </mesh>
    </EarthScene>
  );
}

EarthSphereRoot (Root Primitive)

Just the Earth sphere - use when you want complete control over the scene.

Props:

• radius?: number - Sphere radius (default: EARTH_RADIUS = 6371)
• textureUrl?: string - Main texture
• bumpMapUrl?: string - Bump map
• cloudsMapUrl?: string - Clouds texture
• normalMapUrl?: string - Normal map
• brightness?: number
• enableRotation?: boolean
• emissiveColor?: string - Emissive color (default: "#111111")
• shininess?: number - Material shininess (default: 5)
• bumpScale?: number - Bump map intensity (default: 0.05)

Example:

import { Canvas } from '@react-three/fiber';
import { EarthSphereRoot, EARTH_RADIUS } from '@plexus/earth';

function App() {
  return (
    <Canvas>
      <ambientLight />
      <EarthSphereRoot
        radius={EARTH_RADIUS}
        textureUrl="/earth.jpg"
        enableRotation={true}
      />
    </Canvas>
  );
}

Constants

import {
  EARTH_RADIUS,           // 6371 (scene units)
  EARTH_REAL_RADIUS_KM,   // 6371 km
  EARTH_ROTATION_PERIOD,  // 1 Earth day
  EARTH_ORBITAL_PERIOD,   // 365.25 Earth days
  EARTH_DIAMETER_KM       // 12742 km
} from '@plexus/earth';

Textures

You'll need Earth textures. High-quality free textures are available from:

• NASA Visible Earth
• Solar System Scope

Recommended texture sizes:

• Day map: 4096x2048 or 8192x4096
• Clouds: 2048x1024
• Bump map: 2048x1024

Examples

Rotating Earth with Clouds

<Earth
  dayMapUrl="/textures/earth-day.jpg"
  cloudsMapUrl="/textures/earth-clouds.jpg"
  enableRotation={true}
  brightness={1.3}
/>

Earth with Custom Markers

import { EarthScene, EarthSphereRoot } from '@plexus/earth';

function EarthWithMarkers() {
  return (
    <EarthScene>
      <EarthSphereRoot />
      {/* Marker over New York */}
      <mesh position={[4000, 3000, 2000]}>
        <sphereGeometry args={[100, 16, 16]} />
        <meshStandardMaterial color="red" emissive="red" />
      </mesh>
    </EarthScene>
  );
}

Multiple Earths

import { Canvas } from '@react-three/fiber';
import { EarthSphereRoot } from '@plexus/earth';

function MultipleEarths() {
  return (
    <Canvas>
      <ambientLight />
      <EarthSphereRoot radius={3000} position={[-5000, 0, 0]} />
      <EarthSphereRoot radius={3000} position={[5000, 0, 0]} />
    </Canvas>
  );
}

TypeScript

Fully typed with TypeScript. All props and exports are typed.

import type { EarthProps, EarthSceneProps, EarthSphereRootProps } from '@plexus/earth';

License

MIT

Part of @plexus/ui-aerospace - Primitive-based aerospace components