VoxLogicA UI is a modern web-based interface for visualizing and analyzing neuroimaging data, where analysis are performed through spatial model checking leveraging VoxLogicA.
VoxLogicA is an interpreter of a declarative language, inspired by spatial logics, to analyze images in a simple declarative way. For more information about VoxLogicA itself, please visit the main project repository.
- SvelteKit (v5) - Web framework
- Skeleton UI (v2) - UI components
- TailwindCSS - Styling
- NiiVue - Neuroimaging visualization
- VoxLogicA (v1.3.3-experimental) - Spatial model checking
- Docker
- Node.js (v20 or later)
- Yarn package manager (v1.22.22 or later)
- curl (for downloading VoxLogicA binaries)
- unzip or tar (depending on your OS)
VoxLogicA UI uses three main data directories that you can configure:
- Datasets Directory: contains your neuroimaging data organized by dataset
- Scripts Directory: contains example VoxLogicA scripts
- Workspaces Directory: contains saved user workspaces
DATASET_PATH=static/datasets # Neuroimaging datasets
SCRIPTS_PATH=static/scripts # Example VoxLogicA scripts
WORKSPACES_PATH={temp_dir}/voxlogica-ui/workspaces # User workspacesdatasets/
├── dataset1/
│ ├── case1/
│ │ ├── case1_t1.nii.gz
│ │ └── case1_t2.nii.gz
│ └── case2/
│ ├── case2_t1.nii.gz
│ └── case2_t2.nii.gz
└── dataset2/
└── ...
- Each dataset is a directory containing case directories
- Case directories contain NIFTI files (
.nii.gz) - Layer files should follow the naming convention:
layername.nii.gzor possiblycasename_layername.nii.gz
scripts/
├── example1.imgql
├── example2.imgql
└── ...
- Contains
.imgqlfiles with VoxLogicA scripts - These scripts will be available as examples in the UI
workspaces/
├── workspace1/
│ ├── workspace.json
│ └── cases/
│ └── ...
└── workspace2/
└── ...
- Each workspace has its own directory containing configuration and analysis results
- The application automatically manages this directory structure
You can customize these paths by:
-
Passing the wanted paths to the docker run command (see Installation & Deployment)
-
If not using Docker, creating a
.envfile in the project root:
DATASET_PATH=/path/to/your/datasets
SCRIPTS_PATH=/path/to/your/scripts
WORKSPACES_PATH=/path/to/workspaces- Build the Docker image:
docker build -t voxlogica-ui .- Run the container:
docker run -d \
--name voxlogica-ui \
-p 3000:3000 \
-v "$(pwd)/static/datasets:/data/datasets" \
-v "$(pwd)/static/scripts:/data/scripts" \
voxlogica-uiThis will:
- Start the container in detached mode (
-d) - Map port 3000 to your host machine
- Mount your local datasets and scripts directories into the container (please change the paths in the command above to fit your needs)
Monitor the application logs:
docker logs -f voxlogica-uiStop the container:
docker stop voxlogica-uiRemove the container:
docker rm voxlogica-ui- Install Visual Studio Code and the Dev Containers extension
- Clone the repository and open it in VS Code
- When prompted, click "Reopen in Container"
- The container will automatically:
- Set up the correct Node.js environment
- Install dependencies
- Download the appropriate VoxLogicA binary
- Configure VS Code with recommended extensions
- Run the development server with
yarn dev
- Clone the repository:
git clone https://github.com/CoffeeStraw/VoxLogica-UI/
cd voxlogica-ui- Configure environment variables (optional):
# Create a .env file
touch .envThen set the following paths in the .env file:
# Data paths
DATASET_PATH=/path/to/your/datasets # Default: static/datasets
SCRIPTS_PATH=/path/to/your/scripts # Default: static/scripts
WORKSPACES_PATH=/path/to/workspaces # Default: {temp_dir}/voxlogica-ui/workspaces
# VoxLogicA binary path
VOXLOGICA_BINARY_PATH=/path/to/voxlogica # Default: /opt/voxlogica- Download and install dependencies:
yarn install- Set up VoxLogicA binary:
Download the appropriate VoxLogicA binary from the VoxLogicA releases page and extract the content of the folder in ${VOXLOGICA_BINARY_PATH}.
- Start the development server:
yarn dev- Open your browser and navigate to the development server address displayed in the terminal.
yarn dev- Start development serveryarn build- Build for productionyarn preview- Preview production buildyarn check- Type-check the codebaseyarn format- Format code with Prettieryarn test- Run testsyarn test:coverage- Run tests with coverage report
This software has been developed by Antonio Strippoli as part of his Master Thesis project, under the joint supervision of Vincenzo Ciancia, Fabio Gadducci, Mieke Massink, and the guidance of Giovanna Broccia for user testing and design.
A big thanks as well to all the people who contributed to this project through suggestions, feedback, testing, and code contributions. Every bit of help, no matter how small, has been invaluable in making VoxLogicA UI better.
VoxLogica UI is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.
For more information about VoxLogicA itself, please visit the main project repository.
