Merge pull request #53 from dmritrekker/build

baranaydogan · web-flow · commit 873ea943bbab · 2025-02-28T14:06:02.000+02:00
Build
diff --git a/.github/workflows/build_shared.yml b/.github/workflows/build_shared.yml
@@ -4,9 +4,6 @@ on:
   push:
     branches:
       - build
-  pull_request:
-    branches:
-      - main
 
 jobs:
 
diff --git a/.github/workflows/build_static.yml b/.github/workflows/build_static.yml
@@ -4,9 +4,6 @@ on:
   push:
     branches:
       - build
-  pull_request:
-    branches:
-      - main
 
 jobs:
 
diff --git a/README.md b/README.md
@@ -22,11 +22,33 @@ For complete documentation, tutorials and examples, visit https://dmritrekker.gi
 
 ### Stand-alone executables
 
-Ready-to-run executables are available on the [Releases](https://github.com/dmritrekker/trekker/releases) page. 
+Download the appropriate stand-alone executable for your operating system:
 
-**Note 1:** Linux and macOS users may need to run `chmod +x <trekker_executable>` in their terminal after downloading to make the file executable.
+*   **Linux:** :download: [linux_binary.zip](https://github.com/dmritrekker/trekker/releases/download/v1.0.0-rc3/linux_binary.zip)
+*   **macOS:** :download: [macOS-universal_binary.zip](https://github.com/dmritrekker/trekker/releases/download/v1.0.0-rc3/macOS-universal_binary.zip)
+*   **Windows:** :download: [windows_binary.zip](https://github.com/dmritrekker/trekker/releases/download/v1.0.0-rc3/windows_binary.zip)
+
+After downloading and extracting the archive, you can run the executable.
+
+**Testing:**
+
+- Download and extract the datasets and scripts we prepared for testing by clicking here, [tests.zip](https://github.com/dmritrekker/trekker/releases/download/v1.0.0-rc3/tests.zip).
+- Copy paste your executable under the ``testScripts`` folder.
+- Run the provided test script for your operating system.
+
+
+**Troubleshooting:** 
+
+- *permission denied error*: If you encounter this when trying to run the executable on Linux or macOS, open a terminal, navigate to the directory where you extracted the file, and run the following command:
+
+```bash
+chmod +x <executable name>
+```
+
+Replace ``<executable name>`` with the actual name of the executable file (e.g., ``trekker_linux`` or ``trekker_macOS``).  Then, try running the executable again.
+
+- *macOS errors related to llvm and libomp*: If you encounter errors related to missing OpenMP or libomp, please see the provided test script for macOS in this [link](https://github.com/dmritrekker/trekker/blob/main/tests/testScripts/test_macOS.sh), which gives an example for how to set these paths and install dependencies if needed.
 
-**Note 2:** The stand-alone executables are optimized to work on a wide range of platforms and do not leverage hardware optimization to improve performance. For best performance, executables can be built from source.
 
 
 ### Building from source
diff --git a/doc/other/track2surf/thal.jpg b/doc/other/track2surf/thal.jpg
diff --git a/doc/other/track2surf/thal.svg b/doc/other/track2surf/thal.svg
diff --git a/doc/source/commands/filter.rst b/doc/source/commands/filter.rst
@@ -9,7 +9,7 @@ filters tractograms
 
 .. code-block:: bash
 
-    ./trekker filter [OPTIONS] <input tractogram> <output tractogram>
+    ./trekker filter [OPTIONS] <input tractogram>
 
 |
 
@@ -18,9 +18,6 @@ filters tractograms
 - `<input tractogram> FILE REQUIRED`
   Input tractogram (.vtk, .tck)
 
-- `<output tractogram> FILE REQUIRED`
-  Output tractogram (.vtk, .tck)
-
 |
 
 .. tip::
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -3,7 +3,7 @@ Trekker
 
 .. note::
 
-    February 3\ :sup:`th`, 2025
+    February 6\ :sup:`th`, 2025
 
     **UPDATE:** Trekker v1.0.0-rc3 is out with major improvements and bug fixes! See below for a list of changes.
 
@@ -30,22 +30,58 @@ Installation
 
 Option 1: Stand-alone executables
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Please find the stand-alone executables under `Releases <https://github.com/dmritrekker/trekker/releases>`_.
+
+Download the appropriate stand-alone executable for your operating system:
+
+*   **Linux:** :download:`linux_binary.zip <https://github.com/dmritrekker/trekker/releases/download/v1.0.0-rc3/linux_binary.zip>`
+*   **macOS:** :download:`macOS-universal_binary.zip <https://github.com/dmritrekker/trekker/releases/download/v1.0.0-rc3/macOS-universal_binary.zip>`
+*   **Windows:** :download:`windows_binary.zip <https://github.com/dmritrekker/trekker/releases/download/v1.0.0-rc3/windows_binary.zip>`
+
+After downloading and extracting the archive, you can run the executable.
+
+**Testing:**
+
+- Download and extract the datasets and scripts we prepared for testing by clicking here, `tests.zip <https://github.com/dmritrekker/trekker/releases/download/v1.0.0-rc3/tests.zip>`_.
+- Copy paste your executable under the ``testScripts`` folder.
+- Run the provided test script for your operating system.
+
+
+**Troubleshooting:** 
+
+- *permission denied error*: If you encounter this when trying to run the executable on Linux or macOS, open a terminal, navigate to the directory where you extracted the file, and run the following command:
+
+.. code-block:: bash
+
+    chmod +x <executable name>
+
+Replace ``<executable name>`` with the actual name of the executable file (e.g., ``trekker_linux`` or ``trekker_macOS``).  Then, try running the executable again.
+
+- *macOS errors related to llvm and libomp*: If you encounter errors related to missing OpenMP or libomp, please see the provided test script for macOS in this `link <https://github.com/dmritrekker/trekker/blob/main/tests/testScripts/test_macOS.sh>`_, which gives an example for how to set these paths and install dependencies if needed.
+
+
 
 Option 2: Building from source
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Trekker relies on `nibrary <https://github.com/nibrary/nibrary>`_. To compile Trekker from source, ensure that nibrary is installed first. Then follow these steps to compile Trekker:
+Trekker is natively supported on Linux, Windows, and macOS. Trekker can be installed with a minimal set of standard development tools.
+
+For detailed instructions to build from source, please check the `Readme <https://github.com/dmritrekker/trekker/tree/main>`_ file in GitHub.
+
+Shortly, if your system has CMake (min version 3.15), OpenMP, and a modern compiler. The following should be sufficient for the compilation.
+
+*Note*: clang-v19 is known NOT to work with this version of Trekker due to a conflict with an internal dependency. Please use clang-v18 instead.
 
 **Step 1: Download the Source Code**
 
 .. code-block:: bash
 
-   git clone https://github.com/dmritrekker/trekker
+   git clone https://github.com/dmritrekker/trekker.git
 
 **Step 2: Modify and run the build script**
 
 - **For Linux:** Edit ``build_Linux.sh``
+- **For Windows:** Edit ``build_win.sh``
+- **For macOS:** Edit ``build_macOS.sh``
 
 
 
@@ -161,7 +197,7 @@ Examples
              INP_TRACK.vtk \
              --seed WHITE_MATTER_SURFACE.gii \
              --pathway require_end_inside LEFT_THAL.nii.gz \
-             OUT_TRACK.vtk
+             --output OUT_TRACK.vtk
 
 Release notes for Trekker-v1.0.0-rc3
 ------------------------------------
diff --git a/external/cmake/ExternalNibrary.cmake b/external/cmake/ExternalNibrary.cmake
@@ -1,6 +1,6 @@
 # NIBRARY
 
-SET(NIBRARY_MIN_VERSION "0.3.0" CACHE STRING "Minimum nibrary version") 
+SET(NIBRARY_MIN_VERSION "0.3.1" CACHE STRING "Minimum nibrary version") 
 
 include("${CMAKE_CURRENT_LIST_DIR}/utils.cmake")
 
diff --git a/src/cmd/track.cpp b/src/cmd/track.cpp
@@ -280,7 +280,7 @@ void track(CLI::App *app)
     // General options
     auto general = app->add_option_group(center_text("GENERAL OPTIONS",45));
     
-    general->add_option ("<FOD>",                     fod,                   "Input FOD image (.nii, .nii.gz). Trekker supports both symmetric and asymmetric FODs, i.e. spherical harmonics with both even and odd orders.")->required()->check(CLI::ExistingFile)->type_name("FILE");
+    general->add_option ("<FOD>",                     fod,                   "Input FOD image (.nii, .nii.gz). Trekker supports both symmetric and asymmetric FODs, i.e. spherical harmonics with both even and odd orders.")->required();
     general->add_option ("--output,-o",               out_fname,             "Output tractogram (.vtk, .tck)")->required()->type_name("FILE");
     general->add_flag   ("--saveSeedIndexField",      saveSeedIndexField,    "Save seed indices as tractogram field. Available only for binary vtk output.");
     general->add_flag   ("--ascii,-a",                ascii,                 "Write ASCII output (.vtk only)");
@@ -327,7 +327,7 @@ void track(CLI::App *app)
 
     // Seeding options
     auto seeding = tracking->add_option_group("SEEDING PARAMETERS");
-    seeding->add_option ("--seed, -s",                              seedInp,         "Seed definition")->multi_option_policy(CLI::MultiOptionPolicy::Throw);
+    seeding->add_option ("--seed, -s",                              seedInp,         "Seed definition")->multi_option_policy(CLI::MultiOptionPolicy::Throw)->required();
     seeding->add_option ("--discard_seed",                          discardSeedInp,  "If a seed point falls into this region, it will be discarded")->multi_option_policy(CLI::MultiOptionPolicy::Throw);
     seeding->add_flag   ("--skipSeed",                              skipSeed,        "Does not output the points that are within seed region");
     // seeding->add_flag   ("--allowEdgeSeeds",                        allowEdgeSeeds,  "Allows seeding at the edges of pathway rules. Default: false");
diff --git a/src/main.cpp b/src/main.cpp
@@ -9,6 +9,9 @@ int main(int argc, char *argv[]) {
 
     // Parse input
     CLI::App app(TREKKER_EXE_STRING);
+    
+    argv = app.ensure_utf8(argv);
+
     app.footer("----------" + TREKKER_EXE_STRING + "---------\n© Copyright 2025, Dogu Baran Aydogan, baran.aydogan@uef.fi\n");
     // app.failure_message(CLI::FailureMessage::help);
 
diff --git a/tests/testScripts/test_macOS.sh b/tests/testScripts/test_macOS.sh
@@ -18,7 +18,7 @@ export LDFLAGS="-L${llvm_prefix}/lib -L${libomp_prefix}/lib"
 export OpenMP_omp_LIBRARY="${libomp_prefix}/lib/libomp.dylib"
 
 
-# Make sure trekker_linux is executable
+# Make sure trekker_macOS is executable
 trekker=./trekker_macOS
 
 chmod +x ${trekker}

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ filters tractograms`
`9`	`9`
`10`	`10`	`.. code-block:: bash`
`11`	`11`
`12`		`- ./trekker filter [OPTIONS] <input tractogram> <output tractogram>`
	`12`	`+ ./trekker filter [OPTIONS] <input tractogram>`
`13`	`13`
`14`	`14`	`\|`
`15`	`15`
`@@ -18,9 +18,6 @@ filters tractograms`
`18`	`18`	- `<input tractogram> FILE REQUIRED`
`19`	`19`	`Input tractogram (.vtk, .tck)`
`20`	`20`
`21`		-- `<output tractogram> FILE REQUIRED`
`22`		`- Output tractogram (.vtk, .tck)`
`23`		`-`
`24`	`21`	`\|`
`25`	`22`
`26`	`23`	`.. tip::`