Address TODOs, refactor repeated lines

.github/workflows/ci.yml

@@ -36,7 +36,6 @@ jobs:
         shell: pwsh
         run: |
           choco install ninja -y
-          choco install opencppcoverage -y
           New-Item -ItemType Directory -Force "$env:GITHUB_WORKSPACE\vcpkg_cache" | Out-Null
           git clone https://github.com/microsoft/vcpkg "$env:GITHUB_WORKSPACE\vcpkg"
           & "$env:GITHUB_WORKSPACE\vcpkg\bootstrap-vcpkg.bat"
@@ -48,6 +47,15 @@ jobs:
             zlib `
             --triplet x64-windows
 
+      - name: Install OpenCppCoverage (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $installer = "$env:TEMP\OpenCppCoverageSetup.exe"
+          Invoke-WebRequest -Uri "https://github.com/OpenCppCoverage/OpenCppCoverage/releases/download/release-0.9.9.0/OpenCppCoverageSetup-x64-0.9.9.0.exe" -OutFile $installer
+          Start-Process -FilePath $installer -ArgumentList "/VERYSILENT" -Wait
+          echo "C:\Program Files\OpenCppCoverage" >> $env:GITHUB_PATH
+
       - name: Setup MSVC environment (Windows)
         if: runner.os == 'Windows'
         uses: ilammy/msvc-dev-cmd@v1
@@ -89,7 +97,7 @@ jobs:
         if: runner.os == 'Windows'
         shell: pwsh
         run: >
-          & "$env:ProgramFiles\OpenCppCoverage\OpenCppCoverage.exe"
+          & "C:\Program Files\OpenCppCoverage\OpenCppCoverage.exe"
           --export_type cobertura:coverage.xml
           --sources ${{ github.workspace }}
           -- ctest --test-dir build --output-on-failure -C Release

.gitignore

@@ -20,4 +20,6 @@ docs/api/
 test_package/build
 test_package/CMakeUserPresets.json
 test-data/*
-bench/results*
+bench/results*
+**build-tests
+*.jsonl

README.md

@@ -1,14 +1,49 @@
 # TRX-cpp
+
+[![Documentation](https://readthedocs.org/projects/trx-cpp/badge/?version=latest)](https://trx-cpp.readthedocs.io/en/latest/)
 [![codecov](https://codecov.io/gh/tee-ar-ex/trx-cpp/branch/main/graph/badge.svg)](https://codecov.io/gh/tee-ar-ex/trx-cpp)
 
-TRX-cpp is a C++11 library for reading, writing, and memory-mapping the TRX
-tractography file format (zip archives or on-disk directories of memmaps).
+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.
 
-## Documentation
+## Features
+
+- **Zero-copy memory mapping** — positions, DPV, and DPS arrays are exposed as `Eigen::Map` views directly over memory-mapped files; no unnecessary copies for large tractograms
+- **Streaming writes** — `TrxStream` appends streamlines one at a time and finalizes to a standard TRX archive or directory, suitable when the total count is unknown at the start
+- **Spatial queries** — build per-streamline axis-aligned bounding boxes (AABBs) and efficiently extract spatial subsets; designed for interactive slice-view workflows
+- **Typed and type-erased APIs** — `TrxFile<DT>` gives compile-time type safety; `AnyTrxFile` dispatches at runtime when the dtype is read from disk
+- **ZIP and directory storage** — read and write `.trx` zip archives and plain on-disk directories with the same API
+- **Optional NIfTI support** — read qform/sform affines from `.nii` / `.nii.gz` and embed them in the TRX header
+
+## Quick start
+
+**Dependencies:** a C++17 compiler, [libzip](https://libzip.org/), [Eigen 3.4+](https://eigen.tuxfamily.org/)
+
+```cmake
+# CMakeLists.txt
+find_package(trx-cpp CONFIG REQUIRED)
+target_link_libraries(my_app PRIVATE trx-cpp::trx)
+```
+
+```cpp
+#include <trx/trx.h>
 
-Project documentation (build/usage instructions and API reference) is hosted at
-https://trx-cpp.readthedocs.io/en/latest/.
+// Load any TRX file — dtype detected at runtime
+auto trx = trx::load_any("tracks.trx");
+
+std::cout << trx.num_streamlines() << " streamlines, "
+          << trx.num_vertices()    << " vertices\n";
+
+// Access positions as an Eigen matrix (zero-copy)
+auto positions = trx.positions.as_matrix<float>(); // (NB_VERTICES, 3)
+
+trx.close();
+```
+
+See [Building](https://trx-cpp.readthedocs.io/en/latest/building.html) for platform-specific dependency installation and [Quick Start](https://trx-cpp.readthedocs.io/en/latest/quick_start.html) for a complete first program.
+
+## Documentation
 
+Full documentation is at **[trx-cpp.readthedocs.io](https://trx-cpp.readthedocs.io/en/latest/)**.
 
 ## Third-party notices