# Armillary — a 3D graph view for Obsidian

Your vault's graph, in three dimensions. Orbit it, pull notes around, freeze a
neighbourhood and look at it from the other side.

Armillary is a drop-in companion to the core graph view: the same filters,
groups, display and force controls you already know, rendered in 3D.

![Armillary](assets/hero.png)

![Orbiting the graph](assets/demo.gif)

## Why another 3D graph

- **No dependencies, no WebGL.** ~700 lines of plain JavaScript drawing to a 2D
  canvas with its own perspective projection. Nothing to bundle, nothing to
  ship, no GPU required — it runs the same on an old laptop as on a new one.
- **Feature parity with the core graph.** Not a toy view: search, tags,
  attachments, existing-files-only, orphans, colour groups, arrows, text fade,
  node size, link thickness, and all four force sliders.
- **Themed by your theme.** Colours come from the same CSS variables the core
  graph uses (`--graph-node`, `--graph-line`, `--graph-node-tag`,
  `--graph-node-attachment`, `--graph-node-unresolved`), so it looks like it
  belongs in whatever theme you run.

## Features

| | |
|---|---|
| **Filters** | Search, tags, attachments, existing files only, orphans |
| **Groups** | Any number of colour groups, each with its own query |
| **Colour by** | Folder, tag or link count — automatic, no queries to write |
| **Display** | Arrows, text fade threshold, node size, link thickness |
| **Forces** | Centre, repel, link force, link distance |
| **Freeze** | Lock a note's connections on and orbit around them |
| **Depth** | Fog, glow and size falloff so near and far read apart |

<p align="center">
  <img src="assets/controls.png" width="49%" alt="The controls panel">
  <img src="assets/groups.png" width="49%" alt="Colour groups and tag nodes">
</p>

## Colour

Colour groups work exactly as they do in the core graph — a query and a colour,
as many as you like. On top of that, **Display → Colour by** will colour the
whole graph automatically:

- **Folder** — every folder gets its own hue, so your vault's structure appears
  without writing a single query
- **Tag** — coloured by each note's first tag
- **Link count** — a cold-to-warm heat map, so hubs stand out from leaves

<p align="center">
  <img src="assets/colour-folder.png" width="49%" alt="Coloured by folder">
  <img src="assets/colour-links.png" width="49%" alt="Coloured by link count">
</p>

Hues are derived from the name itself, so a folder keeps its colour between
sessions, and both themes get their own lightness so nothing washes out.

## Controls

| Action | Result |
|---|---|
| Drag | Orbit (with inertia — fling it and it coasts) |
| Scroll | Zoom |
| Shift-drag / right-drag | Pan |
| Hover a node | Highlight it and everything it links to |
| **Alt-click a node** | **Freeze that highlight** so you can orbit around it |
| Drag a node | Move it; it stays where you drop it |
| Click a node | Open the note (Ctrl/Cmd-click for a new tab) |
| Ctrl/Cmd-hover | Page preview popover |
| Double-click | Reset the view and release every pinned node |

The graph auto-frames itself until you take the camera over, and leaves a slow
drift running when idle so the depth stays readable while you think.

Themes are followed in both directions:

<p align="center">
  <img src="assets/light.png" width="70%" alt="Armillary in a light theme">
</p>

## Install

**From Obsidian** — Settings → Community plugins → Browse → search "Armillary"
→ Install → Enable.

**Manually** — download `main.js`, `manifest.json` and `styles.css` from the
[latest release](../../releases/latest) into
`<vault>/.obsidian/plugins/armillary/`, then enable it in Settings → Community
plugins.

Open it with the ribbon icon, or the command **Open 3D graph view**.

## Notes

- The search box matches note names, paths and tags, and understands `path:`,
  `file:`, `tag:`, `-negation` and `"quoted phrases"`. It does not do full-text
  content search.
- Layout is an O(n²) force simulation, comfortable to a couple of thousand
  notes. Beyond that, turn the repel force down or narrow the graph with a
  search first.
- Desktop and mobile both work; on mobile, orbit with one finger.

## Development

No build step — `main.js` is the plugin. Clone into
`<vault>/.obsidian/plugins/armillary/` and reload.

```bash
node test.js
```

covers the graph model (filters, groups, query parsing, link de-duplication),
the force layout, and the camera maths including the drag round-trip.

## Licence

MIT — see [LICENSE](LICENSE).