From 7eb2c91003086425599f513f9617bc659ebabdeb Mon Sep 17 00:00:00 2001
From: Ariel Rokem <arokem@gmail.com>
Date: Thu, 3 Sep 2026 09:31:49 -0400
Subject: [PATCH 1/2] Overhaul front page, remove redundancies.

---
 README.md                                 |   2 +-
 docs/_templates/implementation-links.html |   2 +-
 docs/building.md                          |  11 +-
 docs/concepts.md                          | 107 -------------------
 docs/conf.py                              |   5 +-
 docs/index.md                             |  46 ++++-----
 docs/spec.md                              | 120 ----------------------
 7 files changed, 37 insertions(+), 256 deletions(-)
 delete mode 100644 docs/concepts.md
 delete mode 100644 docs/spec.md

diff --git a/README.md b/README.md
index f6e30b0..31116f9 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 [![Docs](https://img.shields.io/badge/docs-github.io-blue?style=flat&logo=github)](https://tee-ar-ex.github.io/trx-cpp/)
 [![codecov](https://codecov.io/gh/tee-ar-ex/trx-cpp/branch/main/graph/badge.svg)](https://codecov.io/gh/tee-ar-ex/trx-cpp)
 
-A C++17 library for reading, writing, and memory-mapping the [TRX tractography format](https://github.com/tee-ar-ex/trx-spec) — efficient storage for large-scale tractography data.
+A C++17 library for reading, writing, and memory-mapping the [TRX tractography format](tee-ar-ex.github.io) — efficient storage for large-scale tractography data.
 
 ## Features
 
diff --git a/docs/_templates/implementation-links.html b/docs/_templates/implementation-links.html
index 987d3ce..544eaab 100644
--- a/docs/_templates/implementation-links.html
+++ b/docs/_templates/implementation-links.html
@@ -1,7 +1,7 @@
 <div class="sidebar-implementation-links">
   <h3>TRX specification and implementations</h3>
   <ul>
-    <li><a href="https://github.com/tee-ar-ex/trx-spec">TRX Specification</a></li>
+    <li><a href="https://tee-ar-ex.github.io/trx-spec">TRX Specification</a></li>
     <li><a href="https://tee-ar-ex.github.io/trx-python">Python</a></li>
     <li><a href="https://tee-ar-ex.github.io/trx-cpp">C++</a></li>
     <li><a href="https://tee-ar-ex.github.io/trx-rs">Rust</a></li>
diff --git a/docs/building.md b/docs/building.md
index b67dc79..f9a9992 100644
--- a/docs/building.md
+++ b/docs/building.md
@@ -128,9 +128,16 @@ Tests require GTest to be discoverable by CMake (e.g., via a system package or
 `GTest_DIR`). If GTest is not found, tests will be skipped.
 zlib must be discoverable by CMake (`ZLIB::ZLIB`), including for NIfTI I/O.
 
-## Building documentation:
+## Building documentation
 
-Building the docs requires both Doxygen and `sphinx-build` on your PATH.
+Building the docs requires both Doxygen and `sphinx-build` on your PATH, as
+well as some other python dependencies. To install those, run:
+
+```bash
+python -m pip install -r docs/requirements.txt
+```
+
+Then, to build the docs, run:
 
 ```bash
 cmake -S . -B build \
diff --git a/docs/concepts.md b/docs/concepts.md
deleted file mode 100644
index 1556e87..0000000
--- a/docs/concepts.md
+++ /dev/null
@@ -1,107 +0,0 @@
-# Core Concepts
-
-This page explains how TRX-cpp represents tractography data on disk and in
-memory.
-
-## The TRX format
-
-A TRX file is a ZIP archive (or on-disk directory) whose layout directly
-encodes its data model:
-
-- `header.json` — spatial metadata
-- `positions.<dtype>` — all streamline vertices in a single flat array
-- `offsets.<dtype>` — prefix-sum index from streamlines into positions
-- `dpv/<name>.<dtype>` — per-vertex metadata arrays
-- `dps/<name>.<dtype>` — per-streamline metadata arrays
-- `groups/<name>.uint32` — named index sets of streamlines
-- `dpg/<group>/<name>.<dtype>` — per-group metadata arrays
-
-Coordinates are stored in **RAS+ world space** (millimeters), matching the
-convention used by MRtrix3 `.tck` and NIfTI qform outputs.
-
-## Positions array
-
-All streamline vertices are stored in a single flat matrix of shape
-`(NB_VERTICES, 3)`. Keeping all vertices contiguous enables efficient
-memory mapping and avoids per-streamline allocations.
-
-In trx-cpp, `positions` is backed by a `mio::shared_mmap_sink` and
-exposed as an `Eigen::Matrix` view, giving zero-copy read access after
-the file is mapped.
-
-## Offsets and the sentinel
-
-`offsets` is a prefix-sum index of length `NB_STREAMLINES + 1`. Element
-*i* is the offset in `positions` of the first vertex of streamline *i*.
-The final element is a **sentinel** equal to `NB_VERTICES`, which makes
-length computation trivial without special-casing the last streamline:
-
-```cpp
-size_t length_i = offsets[i + 1] - offsets[i];
-```
-
-This design avoids per-streamline allocations and makes slicing the global
-positions array fast and uniform.
-
-## Data per vertex (DPV)
-
-A DPV array stores one value per vertex in `positions`. It has shape
-`(NB_VERTICES, 1)` for scalar fields or `(NB_VERTICES, N)` for
-vector-valued fields. Typical uses:
-
-- FA values along the tract
-- Per-point RGB colors
-- Confidence or weight measures per vertex
-
-DPV arrays live under `dpv/` and are memory-mapped in the same way as
-`positions`.
-
-## Data per streamline (DPS)
-
-A DPS array stores one value per streamline. It has shape
-`(NB_STREAMLINES, 1)` or `(NB_STREAMLINES, N)`. Typical uses:
-
-- Mean FA or average curvature per tract
-- Per-streamline cluster labels
-- Tractography algorithm weights
-
-DPS arrays live under `dps/` and are loaded as typed matrix fields. If the
-on-disk dtype differs from the requested typed reader dtype, values are
-converted during load.
-
-## Groups
-
-A group is a named list of streamline indices stored as a `uint32` array
-under `groups/`. Groups enable sparse, overlapping labeling: a streamline
-can belong to multiple groups, and groups can have different sizes. Typical
-uses:
-
-- Bundle labels (`CST_L`, `CC`, `SLF_R`, ...)
-- Cluster assignments from QuickBundles or similar algorithms
-- Connectivity subsets (streamlines connecting two ROIs)
-
-## Data per group (DPG)
-
-DPG attaches metadata to a group. Each group folder `dpg/<name>/` can
-contain any number of scalar or vector arrays. Typical uses:
-
-- Mean FA across the bundle
-- Per-bundle display color
-- Volume or surface-area estimates
-
-In `TrxFile<DT>`, groups are discovered at load time but loaded lazily on
-first `get_group_members(name)` access, then cached in memory. DPG fields are
-loaded as typed matrices (with dtype conversion when needed).
-
-## Header
-
-`header.json` stores:
-
-- `VOXEL_TO_RASMM` — 4×4 affine mapping voxel indices to RAS+ world
-  coordinates (mm)
-- `DIMENSIONS` — reference image grid dimensions as three `uint16` values
-- `NB_STREAMLINES` — number of streamlines (`uint32`)
-- `NB_VERTICES` — total number of vertices across all streamlines (`uint64`)
-
-The header is primarily for human readability and downstream compatibility.
-The authoritative sizes come from the array dimensions themselves.
diff --git a/docs/conf.py b/docs/conf.py
index 8756308..808de1f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -8,6 +8,7 @@
     "breathe",
     "exhale",
     "sphinx.ext.autosectionlabel",
+    "sphinx_design",
 ]
 
 root_doc = "index"
@@ -49,8 +50,10 @@
 }
 
 myst_enable_extensions = [
-    "colon_fence",
+ "colon_fence",
     "deflist",
+    "fieldlist",
+    "html_image",
     "tasklist",
 ]
 
diff --git a/docs/index.md b/docs/index.md
index 1fe9b7a..19edbbe 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -10,23 +10,22 @@
 :target: https://codecov.io/gh/tee-ar-ex/trx-cpp
 ```
 
-A C++17 library for reading, writing, and memory-mapping the TRX tractography
-format.
+A C++17 library for reading, writing, and memory-mapping the [TRX tractography
+format](https://tee-ar-ex.github.io).
 
+::::{grid} 2
+:::{grid-item-card} Getting Started
 ```{toctree}
-:caption: Getting Started
-:maxdepth: 2
-
+:maxdepth: 1
 introduction
 quick_start
 building
 ```
+:::
 
+:::{grid-item-card} User Guide
 ```{toctree}
-:caption: User Guide
-:maxdepth: 2
-
-concepts
+:maxdepth: 1
 api_layers
 reading
 writing
@@ -34,38 +33,37 @@ streaming
 spatial_queries
 nifti
 ```
+:::
+::::
 
+::::{grid} 2
+:::{grid-item-card} Integration Guide
 ```{toctree}
-:caption: Integration Guide
 :maxdepth: 2
-
 integration
 ```
+:::
 
+:::{grid-item-card} Performance
 ```{toctree}
-:caption: Performance
 :maxdepth: 2
-
 benchmarks
 ```
+:::
+::::
 
+::::{grid}
+:::{grid-item-card} Contributing
 ```{toctree}
-:caption: TRX Format
 :maxdepth: 2
-
-spec
-```
-
-```{toctree}
-:caption: Contributing
-:maxdepth: 2
-
 linting
 ```
+:::
 
+:::{grid-item-card} API Reference
 ```{toctree}
-:caption: API Reference
 :maxdepth: 2
-
 api/library_root
 ```
+:::
+::::
\ No newline at end of file
diff --git a/docs/spec.md b/docs/spec.md
deleted file mode 100644
index 4fbf4b4..0000000
--- a/docs/spec.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# TRX Format Specification
-
-This page documents the on-disk layout and data model of the TRX
-tractography format. TRX-cpp is an implementation of this specification;
-the authoritative specification repository is at
-<https://github.com/tee-ar-ex/trx-spec>.
-
-## General layout
-
-A TRX file is either an **uncompressed or compressed ZIP archive**, or a
-**plain directory**. In both cases the internal structure is identical: the
-file hierarchy describes the data, and filename components encode metadata.
-
-- Each file's **basename** is the name of the metadata field.
-- Each file's **extension** is the dtype (e.g., `float16`, `uint32`).
-- Multi-component arrays encode the number of components between the basename
-  and the extension (e.g., `positions.3.float16` has 3 components per row).
-  Single-component arrays may omit this field for readability.
-
-All arrays use **C-style (row-major) memory layout** and **little-endian
-byte order**.
-
-Compression is optional. Use `ZIP_STORE` for uncompressed storage; use
-`ZIP_DEFLATE` if compression is desired. Compressed files must be
-decompressed before memory-mapping.
-
-## Header
-
-`header.json` is a JSON dictionary with the following fields:
-
-| Field          | Type               | Description               |
-| -------------- | ------------------ | ------------------------- |
-| VOXEL_TO_RASMM | 4×4 array of float | Affine from voxel to RAS+ |
-| DIMENSIONS     | list of 3 uint16   | Reference image grid size |
-| NB_STREAMLINES | uint32             | Number of streamlines     |
-| NB_VERTICES    | uint64             | Total number of vertices  |
-
-The header is primarily for human readability and downstream compatibility
-checks. The authoritative array sizes come from the data arrays themselves.
-
-## Arrays
-
-**positions** (`positions.float16` / `positions.float32` / `positions.float64`)
-
-: All streamline vertices as a contiguous C array of shape `(NB_VERTICES, 3)`.
-  Stored in **RAS+ world space (millimeters)**, matching the MRtrix3 `.tck`
-  convention.
-
-**offsets** (`offsets.uint32` / `offsets.uint64`)
-
-: Prefix-sum index of length `NB_STREAMLINES + 1`. Element *i* is the index
-  in `positions` of the first vertex of streamline *i*. The final element
-  is a sentinel equal to `NB_VERTICES`.
-
-  Streamline length: `length_i = offsets[i+1] - offsets[i]`.
-
-**dpv — data per vertex** (`dpv/<name>.<dtype>`)
-
-: Shape `(NB_VERTICES, 1)` or `(NB_VERTICES, N)`. Values are aligned
-  with `positions` row-by-row.
-
-**dps — data per streamline** (`dps/<name>.<dtype>`)
-
-: Shape `(NB_STREAMLINES, 1)` or `(NB_STREAMLINES, N)`. Values are
-  aligned with streamlines.
-
-**groups** (`groups/<name>.uint32`)
-
-: Variable-length index arrays. Each file lists the 0-based indices of
-  streamlines belonging to the named group. All indices must satisfy
-  `0 ≤ id < NB_STREAMLINES`. Groups are non-exclusive: a streamline may
-  appear in multiple groups.
-
-**dpg — data per group** (`dpg/<group>/<name>.<dtype>`)
-
-: Shape `(1,)` or `(N,)`. Each subdirectory corresponds to one group.
-  Not all metadata fields need to be present in every group.
-
-## Accepted dtypes
-
-| Signed | Unsigned | Float   |
-| ------ | -------- | ------- |
-| int8   | uint8    | float16 |
-| int16  | uint16   | float32 |
-| int32  | uint32   | float64 |
-| int64  | uint64   |         |
-
-## Example structure
-
-```text
-OHBM_demo.trx
-├── dpg/
-│   ├── AF_L/
-│   │   ├── mean_fa.float16
-│   │   ├── shuffle_colors.3.uint8
-│   │   └── volume.uint32
-│   ├── AF_R/  CC/  CST_L/  CST_R/  SLF_L/  SLF_R/
-├── dpv/
-│   ├── color_x.uint8
-│   ├── color_y.uint8
-│   ├── color_z.uint8
-│   └── fa.float16
-├── dps/
-│   ├── algo.uint8
-│   ├── algo.json
-│   ├── clusters_QB.uint16
-│   ├── commit_colors.3.uint8
-│   └── commit_weights.float32
-├── groups/
-│   ├── AF_L.uint32
-│   ├── AF_R.uint32
-│   ├── CC.uint32
-│   ├── CST_L.uint32
-│   ├── CST_R.uint32
-│   ├── SLF_L.uint32
-│   └── SLF_R.uint32
-├── header.json
-├── offsets.uint64
-└── positions.3.float16
-```

From 34ece896e7070d971e7c0ed8dee5fa662142d357 Mon Sep 17 00:00:00 2001
From: Ariel Rokem <arokem@gmail.com>
Date: Thu, 3 Sep 2026 09:35:14 -0400
Subject: [PATCH 2/2] Adds python requirement for sphinx-design.

---
 docs/requirements.txt | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index 2cbf9a4..f724b2a 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -3,3 +3,4 @@ breathe
 exhale
 pydata-sphinx-theme
 myst-parser
+sphinx-design