@samoramachel/netuniverse

v1.3.1

Published

a month ago

Immersive, high-performance 3D graph visualization library for React. It transforms standard relational data into a cinematic "network universe" experience using Three.js and React Three Fiber.

Downloads

296

0High
0Medium
0Low

samoramachel

3D React

NetUniverse Explorer

A beautiful 3D graph visualization library for React built with Three.js and React Three Fiber.

Features

🌌 3D Network Visualization: Immersive particle-based graph rendering with 4000+ background nodes
⚡ Physics Simulation: Cosmos force-directed layout for main nodes
🎨 Interactive Animations:
- Grab interaction (hover to connect)
- Color shift on click (customizable)
- Smooth camera transitions
⚙️ Fully Configurable: Control colors, distances, animations, and camera behavior via config.json
📦 TypeScript Support: Full type definitions included
🎯 Zero Dependencies Bundled: Peer dependencies for minimal bundle size

Installation

npm install netuniverse
# or
yarn add netuniverse

Peer Dependencies

You must install these alongside the library:

npm install react react-dom three

Usage

Basic Example

import { GraphScene, generateGraphData } from 'netuniverse';
import type { GraphData } from 'netuniverse';

// Option 1: Use your own data
const myData: GraphData = {
  nodes: [
    { id: '1', label: 'Node 1', cluster: 'CORE', x: 0, y: 0, z: 0 },
    { id: '2', label: 'Node 2', cluster: 'FINANCE', x: 100, y: 0, z: 0 },
  ],
  links: [
    { source: '1', target: '2' }
  ]
};

// Option 2: Prototype with default random data
const defaultData = generateGraphData();

function App() {
  const [selectedNode, setSelectedNode] = useState(null);

  // Use myData or defaultData
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <GraphScene
        data={defaultData}
        onNodeSelect={setSelectedNode}
        selectedNodeId={selectedNode?.id || null}
      />
    </div>
  );
}

Next.js Usage

'use client';
import dynamic from 'next/dynamic';

const GraphScene = dynamic(
  () => import('NetUniverse-explorer').then(mod => ({ default: mod.GraphScene })),
  { ssr: false }
);

export default function Page() {
  // ... same as above
}

Spatial API (Background Mode)

You can turn the graph into an interactive spatial background by injecting your own 3D content and controlling the camera programmatically.

import { useRef } from 'react';
import { GraphScene, GraphRef } from 'netuniverse';

function MySpatialPage() {
  const graphRef = useRef<GraphRef>(null);

  const handleScrollToFeature = () => {
    // Fly to coordinates [x, y, z] to show a specific 3D feature
    graphRef.current?.flyTo([50, 50, 50], 2);
  };

  return (
    <div style={{ position: 'relative', width: '100vw', height: '100vh' }}>
      {/* 1. Spatial Background */}
      <GraphScene ref={graphRef} data={data}>
        {/* 2. Inject Custom 3D Content */}
        <mesh position={[50, 50, 50]}>
          <boxGeometry args={[10, 10, 10]} />
          <meshStandardMaterial color="orange" wireframe />
        </mesh>
      </GraphScene>

      {/* 3. HTML Overlay */}
      <div style={{ position: 'absolute', zIndex: 10 }}>
        <button onClick={handleScrollToFeature}>Go to Feature</button>
      </div>
    </div>
  );
}

GraphRef API

The ref passed to GraphScene exposes the following methods for programmatic control:

interface GraphRef {
  /** The underlying Three.js camera instance */
  camera: THREE.PerspectiveCamera;
  
  /**
   * Smoothly fly the camera to a specific 3D position.
   * @param position [x, y, z] coordinates
   * @param duration Animation duration in seconds (default: 1.5)
   */
  flyTo: (position: [number, number, number], duration?: number) => void;

  /**
   * Smoothly rotate the camera to look at a specific target point.
   * @param target [x, y, z] coordinates to look at
   * @param duration Animation duration in seconds (default: 1.5)
   */
  lookAt: (target: [number, number, number], duration?: number) => void;
}

Types

export enum ClusterId {
  Core = 'CORE',
  Finance = 'FINANCE',
  Social = 'SOCIAL',
  Infrastructure = 'INFRA',
  Network = 'NETWORK'
}

interface NodeData {
  id: string;
  label: string;
  cluster: ClusterId | string;
  x?: number;
  y?: number;
  z?: number;
  size?: number;
  description?: string;
  connections?: string[];
}

interface LinkData {
  source: string | NodeData;
  target: string | NodeData;
}

interface GraphData {
  nodes: NodeData[];
  links: LinkData[];
}

Advanced Usage

Injecting 3D Content (Spatial Background)

GraphScene acts as a 3D container. specific 3D objects can be injected directly as children, allowing you to mix the graph visualization with other Three.js elements.

<GraphScene data={data}>
  <mesh position={[50, 50, 50]}>
    <boxGeometry args={[10, 10, 10]} />
    <meshStandardMaterial color="orange" wireframe />
  </mesh>
</GraphScene>

Custom Physics Hook

If you need access to the underlying d3-force simulation, you can use the exported useGraphPhysics hook, though standard usage handles this automatically within GalaxyGraph.

import { useGraphPhysics } from 'netuniverse';

// Inside a component within the <Canvas> context
useGraphPhysics({ nodes, links });

Configuration

You can customize the graph behavior by importing and modifying the default config.

Full Options Reference


### Overriding Config via Props (New in v1.3.0)

You can override any specific configuration value by passing a `config` prop to `GraphScene`. This will be merged with the default configuration.

```tsx
const customConfig = {
  graph: {
    colors: {
      background: '#000000', // Override background color
    }
  },
  controls: {
    enableZoom: false // Disable zoom
  }
};

<GraphScene data={data} config={customConfig} />

Development

# Install dependencies
npm install

# Run dev server
npm run dev

# Build library
npm run build

License

MIT

Credits

Built with: