Graphty

Appearance

Camera ​

Guide to camera control and animation.

Overview ​

The camera determines what part of the 3D scene is visible. Control it programmatically for automated tours, saved views, or responsive layouts.

Camera State ​

The camera state includes position, target, and up vector:

typescript
const state = graph.getCameraState();
// Returns:
// {
//   position: { x: 0, y: 0, z: 100 },
//   target: { x: 0, y: 0, z: 0 },
//   up: { x: 0, y: 1, z: 0 }
// }
  • position: Where the camera is located
  • target: What the camera is looking at
  • up: Which direction is "up" for the camera

Setting Camera Position ​

Direct Position Setting ​

typescript
// Set camera position
graph.setCameraPosition({ x: 0, y: 0, z: 100 });

// Set what the camera looks at
graph.setCameraTarget({ x: 0, y: 0, z: 0 });

Zoom to Fit ​

Automatically frame all nodes:

typescript
graph.zoomToFit();

With padding:

typescript
graph.zoomToFit({ padding: 1.2 }); // 20% extra space

Set Complete State ​

typescript
graph.setCameraState({
    position: { x: 50, y: 50, z: 100 },
    target: { x: 0, y: 0, z: 0 },
    up: { x: 0, y: 1, z: 0 },
});

Camera Animation ​

Animate camera movements for smooth transitions:

typescript
const newState = {
    position: { x: 100, y: 100, z: 200 },
    target: { x: 0, y: 0, z: 0 },
    up: { x: 0, y: 1, z: 0 },
};

graph.setCameraState(newState, {
    animate: true,
    duration: 1000, // milliseconds
    easing: "easeInOutQuad", // easing function
});

Available easing functions:

  • linear
  • easeInQuad, easeOutQuad, easeInOutQuad
  • easeInCubic, easeOutCubic, easeInOutCubic
  • easeInExpo, easeOutExpo, easeInOutExpo

Camera Presets ​

Save and restore camera positions:

typescript
// Save current view
graph.saveCameraPreset("overview");

// Navigate to different part of graph
graph.setCameraPosition({ x: 200, y: 0, z: 50 });

// Restore saved view
graph.loadCameraPreset("overview");

// Restore with animation
graph.loadCameraPreset("overview", {
    animate: true,
    duration: 1000,
});

Multiple Presets ​

typescript
// Save multiple presets
graph.saveCameraPreset("top");
graph.setCameraPosition({ x: 0, y: 100, z: 0 });
graph.setCameraTarget({ x: 0, y: 0, z: 0 });

graph.saveCameraPreset("side");
graph.setCameraPosition({ x: 100, y: 0, z: 0 });
graph.setCameraTarget({ x: 0, y: 0, z: 0 });

// Create a tour
const presets = ["overview", "top", "side"];
let current = 0;

function nextView() {
    current = (current + 1) % presets.length;
    graph.loadCameraPreset(presets[current], { animate: true });
}

2D vs 3D Camera ​

3D Mode (Default) ​

Full 3D navigation with orbit controls:

  • Mouse drag: Orbit around target
  • Scroll: Zoom in/out
  • Right-drag: Pan

2D Mode ​

Simplified camera for 2D layouts:

html
<graphty-element view-mode="2d"></graphty-element>
typescript
// 2D camera only has x, y position
graph.setCameraPosition({ x: 0, y: 0, z: 100 });

In 2D mode:

  • Mouse drag: Pan
  • Scroll: Zoom
  • No orbit (camera always looks down at the plane)

Coordinate Transforms ​

Convert between world and screen coordinates:

World to Screen ​

typescript
// Convert 3D world position to 2D screen position
const worldPos = { x: 0, y: 0, z: 0 };
const screenPos = graph.worldToScreen(worldPos);
// Returns: { x: 400, y: 300 } (pixels from top-left)

Use case: Position HTML overlays on nodes:

typescript
const node = graph.getNode("node1");
const screenPos = graph.worldToScreen(node.position);

overlay.style.left = `${screenPos.x}px`;
overlay.style.top = `${screenPos.y}px`;

Screen to World ​

typescript
// Convert screen position to world position
const screenPos = { x: 400, y: 300 };
const worldPos = graph.screenToWorld(screenPos);
// Returns: { x: 0, y: 0, z: 0 }

Camera Events ​

Listen to camera changes:

typescript
graph.on("camera-state-changed", ({ state }) => {
    console.log("Camera moved:", state);
});

Focus on Node ​

Animate camera to focus on a specific node:

typescript
async function focusNode(nodeId) {
    const node = graph.getNode(nodeId);
    if (!node) return;

    const position = node.position;

    graph.setCameraState(
        {
            position: {
                x: position.x,
                y: position.y,
                z: position.z + 50, // Back away a bit
            },
            target: position,
            up: { x: 0, y: 1, z: 0 },
        },
        {
            animate: true,
            duration: 500,
        },
    );
}

Orbit Animation ​

Create a rotating view:

typescript
function startOrbit() {
    let angle = 0;
    const radius = 100;
    const center = { x: 0, y: 0, z: 0 };

    const intervalId = setInterval(() => {
        angle += 0.01;

        graph.setCameraPosition({
            x: center.x + radius * Math.cos(angle),
            y: 20,
            z: center.z + radius * Math.sin(angle),
        });
        graph.setCameraTarget(center);
    }, 16); // ~60fps

    return () => clearInterval(intervalId);
}

const stopOrbit = startOrbit();
// Later: stopOrbit();

Interactive Examples ​