From 16db29f373be36011ff978e79eeabcb593271c19 Mon Sep 17 00:00:00 2001 From: Shashwat325 Date: Mon, 16 Mar 2026 15:56:14 +0000 Subject: [PATCH 1/3] fix:README setup instructions and add Windows/WSL guide --- README.md | 43 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2b201269..8d62fb14 100644 --- a/README.md +++ b/README.md @@ -16,13 +16,52 @@ To try out some BrainBrowser sample applications, simply clone this git repo, an ```Shell $ git clone https://github.com/aces/brainbrowser.git + $ npm install --legacy-peer-deps + $ npm install -g grunt-cli + $ grunt compile $ npm install -g nano-server - $ nano-server 5000 brainbrowser/examples + $ nano-server 5000 examples ``` +### Windows Users + +Windows users must use **WSL (Windows Subsystem for Linux)** because the project uses a Unix symlink (`examples/js/brainbrowser → src/brainbrowser`) that does not work natively on Windows. When git clones the repository on Windows, this symlink is checked out as a plain 23-byte text file instead of an actual directory link. This causes both viewers to show a blank black screen with 404 errors in the browser console because none of the JS files can be found. + +To set up WSL: + +1. Open PowerShell as Administrator and run: +```Shell + $ wsl --install +``` + +2. After completing all the installtaions restart your computer. + +3. Open **Ubuntu** from the Start menu and set up your username and password. + +4. Install Node.js inside WSL (WSL has its own separate environment and does not use your Windows Node.js installation): +```Shell + $ curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - + $ sudo apt-get install -y nodejs +``` + +5. Navigate to your project inside WSL (Windows drives are mounted under `/mnt/`): +```Shell + $ cd /mnt/path/to/brainbrowser +``` + +6. Fix the Unix symlink. When git clones on Windows, the symlink `examples/js/brainbrowser` is saved as a plain text file containing the path `../../src/brainbrowser` instead of acting as a real directory link. This must be manually recreated as a proper Linux symlink inside WSL: +```Shell + $ rm examples/js/brainbrowser + + $ ln -s ../../src/brainbrowser examples/js/brainbrowser +``` + +7. Now run all the setup commands provided above inside the WSL terminal. + + Note that [nano-server](https://www.npmjs.org/package/nano-server) is recommended because it can send **gzip** compressed versions of requested files. If a server without this functionality is used, files in **brainbrowser/examples/models/** and **brainbrowser/examples/color-maps/** will have to be **gunzipped**. -Once the server is running, navigate to to appropriate address (localhost:5000 in the above example) in your browser and select either of the **Surface Viewer** or **Volume Viewer** sample applications. +Once the server is running, navigate to appropriate address (localhost:5000 in the above example) in your browser and select either of the **Surface Viewer** or **Volume Viewer** sample applications. Surface Viewer -------------- From 6ecffd54a60ea570ae41ed276e7f2ab76a24c173 Mon Sep 17 00:00:00 2001 From: Shashwat325 <149855912+Shashwat325@users.noreply.github.com> Date: Tue, 17 Mar 2026 18:29:53 +0530 Subject: [PATCH 2/3] fix:README.md instructions updated --- README.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 8d62fb14..fe112c2b 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,15 @@ To set up WSL: $ ln -s ../../src/brainbrowser examples/js/brainbrowser ``` -7. Now run all the setup commands provided above inside the WSL terminal. +7. Now run all these commands in the WSL terminal: + ```Shell + $ git clone https://github.com/aces/brainbrowser.git + $ npm install --legacy-peer-deps + $ npm install -g grunt-cli + $ grunt compile + $ npm install -g nano-server + $ nano-server 5000 examples +``` Note that [nano-server](https://www.npmjs.org/package/nano-server) is recommended because it can send **gzip** compressed versions of requested files. If a server without this functionality is used, files in **brainbrowser/examples/models/** and **brainbrowser/examples/color-maps/** will have to be **gunzipped**. From 4bca60468677596a956238181fdade197f738997 Mon Sep 17 00:00:00 2001 From: Shashwat325 <149855912+Shashwat325@users.noreply.github.com> Date: Tue, 17 Mar 2026 18:34:36 +0530 Subject: [PATCH 3/3] fix:README.md instructions updated --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fe112c2b..5974fb1b 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ To set up WSL: ``` 7. Now run all these commands in the WSL terminal: - ```Shell +```Shell $ git clone https://github.com/aces/brainbrowser.git $ npm install --legacy-peer-deps $ npm install -g grunt-cli