From 5c2e812c8834d6b016e11616cce02c44265bd091 Mon Sep 17 00:00:00 2001 From: Ariel Rokem Date: Thu, 3 Sep 2026 08:48:08 -0400 Subject: [PATCH 1/5] DOC: Removes fencepost section, because this is part of the spec now. --- docs/implementation-notes.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/implementation-notes.md b/docs/implementation-notes.md index 77bbf48..6529609 100644 --- a/docs/implementation-notes.md +++ b/docs/implementation-notes.md @@ -6,17 +6,6 @@ The TRX specification allows streamline positions to use the float16 datatype, which is not native to JavaScript. This code converts float16 values to float32 using a lookup table for performance. -## Fencepost Problem - -The TRX specification stores NB_STREAMLINES values in the offsets array, with -each value pointing to the start of that streamline. One must use the length of -the positions array or the header to infer the end of the final streamline. - -This code returns an offset array with NB_STREAMLINES + 1 values to solve the -[fencepost problem](https://icarus.cs.weber.edu/~dab/cs1410/textbook/3.Control/fencepost.html) -for the final streamline. This simplifies and accelerates display code, but you -must be aware of this modification when comparing with other implementations. - ## Endianness The TRX specification requires little-endian byte order. The current code only From 3fea460135f65d6d1ef518b7fe05fbef97c3d633 Mon Sep 17 00:00:00 2001 From: Ariel Rokem Date: Thu, 3 Sep 2026 08:50:41 -0400 Subject: [PATCH 2/5] Improve front page text. --- docs/index.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 05f9735..95e1e88 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,8 @@ -# trx-javascript +# TRX in javascript -A minimal JavaScript reader for brain tractography streamline formats: -**TRX**, **TRK**, **TCK**, **VTK**, and **TT** (DSI Studio). +This library provides a minimal JavaScript reader for brain tractography streamline +formats, including **TRX**, but also **TRK**, **TCK**, **VTK**, and +**TT** ([DSI Studio](https://dsi-studio.labsolver.org/)). ```{toctree} :maxdepth: 2 From 23c2482cd35ee557a5b76d6a4b8c1a6605cd09f4 Mon Sep 17 00:00:00 2001 From: Ariel Rokem Date: Thu, 3 Sep 2026 08:53:12 -0400 Subject: [PATCH 3/5] Prettify front page with cards. --- docs/conf.py | 3 +++ docs/index.md | 14 +++++++++++--- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 2fb8877..bfd930b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,6 +12,7 @@ 'myst_parser', 'sphinx_js', 'sphinx.ext.autosectionlabel', + 'sphinx_design', ] js_source_path = os.path.abspath(os.path.join(os.path.dirname(__file__), '..')) @@ -52,6 +53,8 @@ myst_enable_extensions = [ "colon_fence", "deflist", + "fieldlist", + "html_image", "tasklist", ] diff --git a/docs/index.md b/docs/index.md index 95e1e88..eaa47d9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,13 +4,21 @@ This library provides a minimal JavaScript reader for brain tractography streaml formats, including **TRX**, but also **TRK**, **TCK**, **VTK**, and **TT** ([DSI Studio](https://dsi-studio.labsolver.org/)). -```{toctree} -:maxdepth: 2 -:caption: Contents +::::{grid} 2 +:::{grid-item-card} Usage documentation +```{toctree} +:maxdepth: 1 getting-started api formats +``` +::: +:::{grid-item-card} Development and benchmarks +```{toctree} +:maxdepth: 2 implementation-notes benchmark ``` +::: +:::: From 6548aece4e3b48186299874c9ddb97cba4c258e8 Mon Sep 17 00:00:00 2001 From: Ariel Rokem Date: Thu, 3 Sep 2026 09:03:46 -0400 Subject: [PATCH 4/5] Adds a Makefile to make docbuilds easier. Added some instructions in the README. --- Makefile | 20 ++++++++++++++++++++ README.md | 17 ++++++++++++++++- 2 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 Makefile diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..453b39f --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = docs +BUILDDIR = docs/_build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/README.md b/README.md index 02c1690..0b07fb5 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,21 @@ node bench.mjs dpsv.trx ## Documentation -Full documentation is available at (GitHub Pages URL). +Full documentation is available at the +[project website](https://tee-ar-ex.github.io/trx-javascript). + +### Building the documentation + +To build the documentationl locally, install jsdoc: + + npm install -g jsdoc + +And python dependencies: + + pip install sphinx myst-parser pydata-sphinx-theme sphinx-js + +And then run `make html` + + From 6408fd720e25176c61a7c7bd4f5ae34ca592b5aa Mon Sep 17 00:00:00 2001 From: Ariel Rokem Date: Thu, 3 Sep 2026 09:04:52 -0400 Subject: [PATCH 5/5] Install required sphinx-design extension. --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a744834..55360c7 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,7 +20,7 @@ jobs: python-version: '3.11' - name: Install Python dependencies run: | - pip install sphinx myst-parser pydata-sphinx-theme sphinx-js + pip install sphinx myst-parser pydata-sphinx-theme sphinx-js sphinx-design - name: Install JSDoc run: npm install -g jsdoc - name: Build docs