Codex Constellation

A cinematic, customizable 3D knowledge graph for Obsidian. It turns notes, conversation archives, and reusable ideas into luminous semantic constellations with smooth camera travel, readable labels, GPU-rendered depth, and an optional feminine celestial background.

Highlights

• Real 3D force-directed layout with meaningful X/Y/Z depth
• Web Worker layout simulation and aggregated GPU rendering
• Curved, interruptible camera flights with zero-jerk easing
• Global, semantic-family, and local-neighborhood navigation
• Persistent high-priority labels plus collision-aware local labels
• Semantic cluster colors and configurable folder/tag coloring
• Search, hover neighborhoods, focus cards, filters, tags, orphans, and unresolved links
• Bloom, fog, spacing, physics, label, link, camera, and quality controls
• Optional princess-galaxy artwork that can be toggled independently
• Optional replacement for Obsidian's native Open graph view action
• English, Chinese, German, Italian, Spanish, and Portuguese UI
• Markdown and Canvas graph support

Privacy

Codex Constellation runs locally. It does not upload vault contents, include telemetry, or make network requests. This repository contains no personal vault data, conversation archive, saved graph positions, or local plugin settings.

Install

Latest release

1. Download main.js, manifest.json, and styles.css from the latest GitHub release.
2. Create <your-vault>/.obsidian/plugins/codex-constellation/.
3. Copy the three files into that folder.
4. Reload Obsidian and enable Codex Constellation under Settings → Community plugins.

Build from source

npm ci
npm test
npm run lint
npm run build

The installable files are written to dist/.

Usage

Open the orbit ribbon icon or run Codex Constellation: Open. By default, opening Obsidian's native graph redirects to Codex Constellation; disable this under the plugin settings if you want both graph views.

Controls:

• Drag to orbit
• Right-drag or modifier-drag to pan
• Scroll to zoom
• Click a node to select and smoothly frame its semantic family
• Double-click/open from the card to open the note
• F frames the selected node
• R returns to the global view
• WASD plus Q/E enables free flight

Architecture

• src/data/ — vault graph model, semantic clustering, filters, tags, Canvas links
• src/layout/ — worker and main-thread 3D force simulation
• src/render/ — Three.js aggregate renderer, shaders, links, stars, nebulae
• src/interactions/ — camera director and navigation input
• src/overlay/ — labels, collision avoidance, cards, and controls
• src/view/ — Obsidian view and application orchestration
• tests/ — deterministic graph, camera, timing, rendering, and settings tests

Attribution

Codex Constellation was rebuilt from the MIT-licensed Galaxy View renderer foundation and retains attribution to its contributors. The current semantic archive experience, cinematic navigation, celestial background system, label behavior, and native-graph integration are part of this project.

License

MIT