# Brain Graph

An Obsidian plugin that draws your vault as a brain, in 2D or 3D. It's a lightweight alternative to the core graph view.

![Brain Graph showing a vault as a 3D brain](./images/brain-graph.webp)

- **Neurons:** each note is a point on the cortex. The 10 most connected notes always show their names.
- **Regions:** each community of notes (detected from links) or each top-level folder becomes a region of the cortex. Tightly connected groups sit next to each other.
- **Orphans:** notes without links live in the cerebellum.
- **Fibers:** the links. With the surface off (default), they dive toward the center like white matter. With the surface on, they arch over the outside.
- **Stable map:** positions are saved, so the brain always opens the same way. New notes land near their neighbors without shuffling the rest.
- **Fits your theme:** light and dark modes follow Obsidian, using your theme's background and interface colors.
- **Your colors:** pick a ready-made palette, paint a region straight from the legend, or color notes by folder, tag or a `color` property. No queries to write.

![Idle animation with pulses running along the links](./images/brain-graph-idle.webp)

![Light mode following a light Obsidian theme](./images/brain-graph-light.webp)

## Installation

### From Community plugins

1. Open *Settings → Community plugins → Browse* and search for **Brain Graph**.
2. Select **Install**, then **Enable**.

### Manual

1. Download `main.js`, `manifest.json` and `styles.css` from the [latest release](https://github.com/HernanJr0/brain-graph/releases/latest).
2. Put them in `<vault>/.obsidian/plugins/brain-graph/` (create the folder if needed).
3. In *Settings → Community plugins*, reload the list and enable **Brain Graph**.

Open it from the brain icon in the ribbon or with Ctrl/Cmd+P → "Brain Graph: Open graph view".

On first open, the plugin computes the layout (a few seconds, depending on vault size) and writes `layout.json` to the plugin folder. Later opens are instant.

When updating manually, replace the files and **restart Obsidian**. Toggling the plugin off and on with the new version may fail to load.

## Usage

- **Navigate:** drag to orbit (3D) or pan (2D), scroll to zoom. Click a note to open it; Ctrl/Cmd+click opens it in a new tab.
- **Graph toolbar:** switches 2D/3D, jumps to side, top and front views, toggles cortex, surface, depth of field, glow and ambient pulses, and has a search by note name.
- **Region colors:** the palette button in the toolbar opens the legend. Hover a region to highlight it in the brain, click its dot to pick a color (it updates live), and use ↺ to go back to the palette. You can also right-click a note → *Color this region…*.
- **Commands:** "Open graph view", "Recalculate layout" and "Toggle 2D/3D".

### Colors

From the simplest to the most detailed:

1. **Palette:** *Nebula* (default), *Aurora*, *Ember*, *Pastel*, *Accent* (shades of your theme's accent color) and *Colorblind safe* (Okabe-Ito). Each one has a light and a dark variant.
2. **Legend:** paint a region with any color. With *Group regions by: Links*, the color sticks to the region's five most connected notes, so it survives renames, new notes and even deleting the hub.
3. **Color rules:** in the settings, color every note in a folder (subfolders included) or with a tag (nested tags included). The first matching rule wins; drag to reorder. Each rule shows how many notes it matches.
4. **Color property:** `color: "#ff8800"` in a note's frontmatter colors that note. Invalid values are ignored.

Priority: color property > rules > legend > palette. In light mode, your own colors are darkened if needed so they stay visible on the light background (and lightened in dark mode).

### Settings

| Option | Default | What it does |
| --- | --- | --- |
| Default mode | 3D | How the graph opens |
| Appearance | Follow Obsidian | Light or dark. *Follow Obsidian* switches together with your theme and uses its background; *Dark* or *Light* force a mode |
| Group regions by | Links | Link communities or top-level folder |
| Show orphan notes | on | Notes without links in the cerebellum |
| Brain surface | off | Translucent surface with notes on the outside, instead of the point cloud |
| Depth of field | on | Blurs and dims what is behind the center |
| Show cortex | on | Anatomical outline: fissures, sulci, lobes, cerebellum and brainstem |
| Node glow | on | Halo around notes |
| Hover pulses | on | Signals run along the links of the hovered note |
| Ambient pulses | on (45) | Slow signals all the time |
| Idle animation | on | After about 1.5 s without input: a wave of activity, breathing glow, and the interface fades out |
| Idle orbit | on | The camera slowly orbits while idle (3D) |
| Node size / Hub labels | 1 / on | Appearance |
| Color palette | Nebula | Colors of the regions, largest region first |
| Color property | `color` | Frontmatter property with a note's own color; empty turns it off |
| Reset region colors | — | Regions painted in the legend go back to the palette |
| Color rules | none | Color notes by folder or tag; the first match wins |
| Recalculate layout | — | Lays everything out again from scratch |

## Performance

The plugin is built to run at 20 fps or more on integrated GPUs.

- **On-demand rendering:** it only redraws when something changes. For zero cost while the brain is still, turn off **ambient pulses** and **idle animation**. With either one on, the loop runs at about 30 fps.
- **Auto pause:** rendering stops when the tab is hidden.
- **Finite layout:** the layout converges and stops, with O(n) repulsion via a spatial hash. The result is stored in `layout.json`.
- **LOD:** depth of field reduces detail in the background.

## Privacy

Brain Graph works fully offline. It lists the Markdown files in your vault and reads their links, tags and color property through Obsidian's metadata cache to build and color the graph; note contents never leave your machine. It makes no network requests, and only writes `data.json` (settings) and `layout.json` (positions) inside its own plugin folder.

## Development

Requires Node.js 22 and npm.

```bash
npm install
npm run dev      # watch → main.js with sourcemap
npm run build    # type-check (tsc) + minified build
npm run deploy   # build + copy to a test vault
```

`deploy` uses the path given as an argument (`npm run deploy -- "<vault>"`), or the `BRAIN_GRAPH_VAULT` variable, or `~/Documents/BrainGraph-Teste`.

### Preview outside Obsidian

`dev/preview.ts` renders the brain with a fake vault in the browser:

```bash
npx esbuild dev/preview.ts --bundle --format=iife --outfile=dev/preview.js
python -m http.server 5178   # open http://localhost:5178/dev/index.html
```

URL parameters:
- `n`: number of notes (default 1500).
- `clusters`: number of groups.
- `orphans`: fraction of orphan notes.
- `mode=2d`.
- `view=superior|frontal`.
- `cloud`: no surface.
- Effects to turn off: `nodof`, `noglow`, `noambient`, `noidle`.
- Simulated Obsidian theme: `obsidian=dark|light`, with `bg=<color>` for the theme background (hex without `#`, or a CSS function such as `oklch(…)`).
- `theme=auto|dark|light`: the Appearance setting (default `auto` when `obsidian` is set, otherwise `dark`).
- `palette=aurora|ember|pastel|accent|okabe-ito`: the color palette (default Nebula).

### Measurement scripts

Bundle with `npx esbuild dev/<script>.ts --bundle --platform=node --outfile=dev/<script>.js` and run with `node`:

- `dev/bench.ts`: graph and layout time with 1.5k, 8k and 20k synthetic notes.
- `dev/quality.ts [vault]`: on a real vault, measures link length, reopening, new notes and distribution per lobe.
- `dev/affinity.ts`: checks that connected communities end up as neighbors.

### Structure

| File | Role |
| --- | --- |
| `src/main.ts` | Plugin: view, commands, settings and persistence in `layout.json` |
| `src/view.ts` | ItemView: toolbar, search, region legend, context menu, opening notes, incremental rebuild |
| `src/graph-core.ts` | Graph from resolved links, with communities via label propagation plus modularity merging, in a stable order |
| `src/layout.ts` | Affinity-based seeds, cortex slots by area, spatial-hash forces and projection onto the anatomy |
| `src/brain-shape.ts` | Procedural SDF anatomy: stylized hemispheres, sulci, cerebellum and brainstem |
| `src/colors.ts` | Palettes, regions and their anchors, folder/tag rules and the color property |
| `src/theme.ts` | Light and dark themes: every scene color, and reading the Obsidian theme and background |
| `src/renderer.ts` | Three.js: nodes, halos, fibers, pulses, surface, depth of field, idle animation and picking |
| `src/settings.ts` | Settings |

### Release

Releases are published by GitHub Actions (`.github/workflows/release.yml`):

1. Update `version` in `manifest.json` and `package.json`, and add the version to `versions.json`.
2. Commit, create an annotated tag **without a `v` prefix** (Obsidian requires the tag to match the manifest version exactly) and push: `git tag -a 1.0.1 -m "Brain Graph 1.0.1" && git push origin main 1.0.1`.
3. The workflow checks that the tag matches `manifest.json`, builds, attests the build provenance, and publishes `main.js`, `manifest.json` and `styles.css`.

To republish an existing tag, use *Actions → Release → Run workflow* and enter the tag.

## License

[MIT](LICENSE)