Unified NIRS Analysis Desktop Application

A modern desktop application for Near-Infrared Spectroscopy (NIRS) data analysis, combining the power of the nirs4all Python library with a sleek React-based user interface.

Download • User Guide • nirs4all Library • Website

---

Playground — Interactive spectral exploration with PCA, distributions, and preprocessing preview

---

Which nirs4all do you need?

nirs4all comes in two flavors — pick the one that fits your workflow:

	nirs4all Studio (Desktop App)	nirs4all (Python Library)
Best for	Researchers, technicians, and anyone who prefers a visual interface	Developers, data scientists, and anyone who writes Python scripts
What it is	A desktop application with drag-and-drop pipelines, interactive charts, and one-click model training	A pip install Python package with a declarative API for building NIRS pipelines in code
Install	Download the installer	pip install nirs4all
Repository	You are here	GBeurier/nirs4all

Not sure? If you've never written Python code, start here with nirs4all Studio. It uses the nirs4all Python library under the hood and gives you all the same capabilities through a graphical interface.

---

Installation

nirs4all Studio offers three ways to get started, depending on your needs:

Option 1 — Installer (Recommended)

The simplest option. Downloads and installs like any desktop application.

1. Go to the latest release

2. Download the installer for your platform:

   Platform	File
   Windows	.exe installer
   macOS (Intel & Apple Silicon)	.dmg disk image
   Linux	.AppImage or .deb package

3. Run the installer and launch nirs4all Studio

The installer ships the Studio app and backend source, then creates or reuses a writable Python runtime outside the app bundle. You normally don't need Python installed on your machine, but first launch may download and configure the managed runtime.

GPU support: GPU-capable dependencies are selected by the managed runtime profile, not by a separate GPU installer filename. The all-in-one bundle currently ships the locked V1 CPU profile.

Option 2 — All-in-one Standalone (Portable)

A self-contained archive — just extract and run. No installation, no admin rights needed. Ideal for trying nirs4all Studio without committing to an install, or for machines where you can't install software.

1. Go to the latest release

2. Download the all-in-one archive for your platform:

   Platform	File
   Windows	nirs4all Studio-*-all-in-one-win-x64.zip
   macOS	nirs4all Studio-*-all-in-one-mac-*.zip
   Linux	nirs4all Studio-*-all-in-one-linux-x64.tar.gz

3. Extract the archive and run the executable inside

Everything is bundled — Python runtime, backend, and frontend. Nothing else to install.

Option 3 — Developer Setup (From Source)

For contributors, or if you want to hack on the code. Requires Node.js 20+ and Python 3.11+.

git clone https://github.com/GBeurier/nirs4all-studio.git
cd nirs4all-studio
npm install

Then set up the Python backend and start the servers — see Getting Started below.

Installation comparison

	Installer	Standalone	Developer
Install required	Yes	No (extract & run)	Clone + npm install
Python required	No preinstall; managed at first launch	No (bundled)	Yes (3.11+)
Auto-updates	Yes	Manual re-download	git pull
Runtime profile	Managed CPU/GPU-capable profiles	Locked V1 CPU profile	Your choice
Best for	End users	Portable / trial use	Contributors

---

Getting Started

This section is for developers running from source (Option 3 above). If you installed via the Installer or Standalone, just launch the app — no setup needed.

Prerequisites

• Node.js 20+ (recommended: use nvm + the version in .nvmrc)
• Python 3.11+
• nirs4all library (optional for UI development)

Cross-Platform Support

This project supports development on:

• Windows Native - PowerShell, cmd.exe, or Windows Terminal
• Linux - Any distribution with Node.js and Python
• macOS - Intel and Apple Silicon
• WSL2 - Windows Subsystem for Linux

---

Windows Native Setup

1. Install Node dependencies:

   npm install

2. Install Python dependencies:

   python -m venv .venv
   .venv\Scripts\activate
   pip install -r requirements-cpu.txt

3. Check your environment:

   npm run doctor

4. Start development servers:

   Use the cross-platform launcher for the full web stack:

   scripts\launcher.cmd start web:dev
   scripts\launcher.cmd stop

   Or run frontend and backend separately:

   npm run dev          REM Frontend (Vite) at http://localhost:5173

   Terminal 2:

   .venv\Scripts\activate
   python -m uvicorn main:app --reload --port 8000

   Desktop mode:

   npm run start:desktop

---

Linux / macOS Setup

1. Install Node dependencies:

   npm install

2. Install Python dependencies:

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements-cpu.txt  # or requirements-gpu.txt for GPU

3. Check your environment:

   npm run doctor

4. Start development servers:

   Use the cross-platform launcher for the full web stack:

   ./scripts/launcher.sh start web:dev
   ./scripts/launcher.sh stop

   Or run frontend and backend separately:

   npm run dev          # Frontend (Vite) at http://localhost:5173

   Terminal 2:

   source .venv/bin/activate
   python -m uvicorn main:app --reload --port 8000

   Desktop mode:

   npm run start:desktop

---

WSL2 Setup (Windows Subsystem for Linux)

If you prefer using WSL2, make sure you're using Linux node/npm (not the Windows ones mounted under /mnt/c).

1. One-time: permanently disable Windows PATH injection into WSL (prevents UNC/cmd.exe install failures):

   sudo tee /etc/wsl.conf <<'EOF'
   [interop]
   appendWindowsPath=false
   EOF

   Then restart WSL from Windows:

   wsl.exe --shutdown

2. Install/use Node via nvm (WSL-native):

   npm run setup:wsl
   nvm use

Quick check (should NOT point to /mnt/c/...):

which node
which npm

Then follow the Linux setup instructions above.

---

Desktop Mode (Electron)

To run as a desktop application:

# Development mode (with hot reload)
npm run dev:electron

# Build and preview (production mode)
npm run electron:preview

The Electron main process automatically spawns the Python backend and manages its lifecycle.

Note: The webapp can run without nirs4all installed for pure UI development. The backend will report missing capabilities but the frontend is fully functional.

---

Screenshots

Pipeline Editor — Drag-and-drop builder with component library, validation, and hyperparameter tuning

Left: Results with model ranking and CV scores — Right: Runs overview and monitoring

Left: Inspector — prediction analysis and model diagnostics — Right: SHAP variable importance

Left: Spectra Synthesis — realistic NIR data generation — Right: Predictions analysis

---

Features

• Spectral Data Visualization — Interactive charts for exploring NIRS spectra
• Pipeline Builder — Visual drag-and-drop pipeline construction
• Experiment Wizard — Guided experiment setup with preset templates
• Prediction Engine — Run trained models on new samples
• SHAP Explainability — Variable importance and model interpretation
• Spectra Synthesis — Generate realistic synthetic NIR data
• Transfer Analysis — Instrument transfer and domain adaptation tools
• Workspace Management — Organize datasets, pipelines, and results
• Native Desktop Experience — Runs as a standalone desktop app via Electron
• GPU Acceleration — CUDA (Linux/Windows) and Metal (macOS) support

---

Tech Stack

Frontend

• React 19 with TypeScript (strict mode)
• Vite for fast development and optimized builds
• Tailwind CSS with custom scientific design system
• shadcn/ui component library
• TanStack Query for API state management
• Framer Motion for smooth animations

Desktop Shell

• Electron 40 for cross-platform desktop experience
• Chromium for consistent WebGL support across all platforms
• IPC Bridge for secure main/renderer communication

Backend

• FastAPI for high-performance REST API
• nirs4all Python library for all NIRS analysis
• WebSocket for real-time training progress updates
• PyInstaller for standalone backend packaging

---

Project Structure

nirs4all_webapp/
├── src/                    # React frontend source
│   ├── components/         # UI components
│   │   ├── layout/         # App layout (sidebar, header)
│   │   ├── pipeline-editor/# Pipeline Editor (see Architecture)
│   │   └── ui/             # shadcn/ui components
│   ├── context/            # React context providers
│   ├── data/               # Data models and registries
│   │   └── nodes/          # Node registry system
│   ├── lib/                # Utilities and helpers
│   ├── api/                # API client
│   ├── types/              # TypeScript type definitions
│   │   └── electron.d.ts   # Electron IPC types
│   └── pages/              # Route components
├── electron/               # Electron main process
│   ├── main.ts             # Main entry point (window management)
│   ├── preload.ts          # Secure IPC bridge (contextBridge)
│   ├── backend-manager.ts  # Python backend lifecycle management
│   ├── env-manager.ts      # Python environment detection and setup
│   └── logger.ts           # Persistent file logging
├── api/                    # FastAPI backend
│   ├── workspace.py        # Workspace management routes
│   ├── datasets.py         # Dataset operations
│   ├── pipelines.py        # Pipeline CRUD
│   ├── predictions.py      # Prediction storage
│   └── system.py           # Health, system info, and GPU detection
├── scripts/                # Build and utility scripts
│   ├── build-backend.cjs   # Python backend packaging (cross-platform)
│   └── build-release.cjs   # Full release build (cross-platform)
├── build/                  # Build configuration
│   └── entitlements.mac.plist  # macOS code signing entitlements
├── docs/                   # Documentation
│   └── _internals/         # Developer guides
├── public/                 # Static assets
├── main.py                 # FastAPI application entry
├── backend.spec            # PyInstaller spec file (backend executable)
├── electron-builder.installer.yml  # Electron packaging config (installer)
├── electron-builder.archive.yml    # Electron packaging config (portable archive)
└── package.json            # Node dependencies

---

Scripts

Launcher (Cross-Platform)

Use the unified launcher for all modes:

Windows	Linux/macOS	Description
scripts\launcher.cmd start web:dev	./scripts/launcher.sh start web:dev	Start frontend + backend (web dev)
scripts\launcher.cmd start desktop:dev	./scripts/launcher.sh start desktop:dev	Start Electron desktop (dev)
scripts\launcher.cmd stop	./scripts/launcher.sh stop	Stop all servers
scripts\launcher.cmd status	./scripts/launcher.sh status	Show server status

Direct scripts are also available: npm run dev for Vite, python -m uvicorn main:app --reload --port 8000 for the backend, and npm run start:desktop for Electron.

npm Scripts - Development

Command	Description
npm run doctor	Check Node, npm, Python, lockfile, and requirement files
npm run dev	Start Vite dev server
npm run dev:electron	Start Electron with hot reload
npm run start:desktop	Alias for Electron development mode
npm run lint:parallel	Run ESLint, TypeScript, node registry, Ruff, and dependency checks
npm run test:frontend	Run Vitest tests
npm run test:backend	Run pytest backend tests
npm run test:routes	Check FastAPI route table uniqueness
npm run test:parallel	Run Vitest and pytest together
npm run test:e2e	Run Playwright web Chromium tests

npm Scripts - Production Builds

Command	Description
npm run build	Build frontend for production
npm run build:electron	Build Electron app
npm run electron:preview	Preview Electron production build
npm run release	Build an installer release
npm run release:clean	Clean and rebuild an installer release
npm run release:all-in-one	Build a portable all-in-one archive
npm run release:all-in-one:clean	Clean and rebuild a portable all-in-one archive

Release Entry Points

Installer and all-in-one builds use separate entry points:

• Installer — npm run release -- --platform win|mac|linux packages with electron-builder.installer.yml and produces platform-native installers plus the Windows portable executable.
• All-in-one — npm run release:all-in-one:clean -- --platform win32|linux|darwin --arch x64|arm64 bakes the embedded runtime, packages with electron-builder.archive.yml, and produces the portable archive.

npm run release -- --clean --platform win
npm run release:all-in-one:clean -- --platform win32 --arch x64

npm Scripts - Packaging

Command	Description
npm run release -- --platform win	Package for Windows
npm run release -- --platform mac	Package for macOS
npm run release -- --platform linux	Package for Linux
npm run release -- --platform all	Package for all platforms

---

Logging and Crash Reporting

Persistent Logs

In desktop mode, all main process logs are written to rotating log files:

OS	Log location
Windows	%APPDATA%\nirs4all-webapp\logs\
macOS	~/Library/Application Support/nirs4all-webapp/logs/
Linux	~/.config/nirs4all-webapp/logs/

Sentry Crash Reporting (optional)

Automatic crash reporting via Sentry can be enabled by setting the SENTRY_DSN environment variable. This captures errors from the Electron main process, the React frontend, and the Python backend.

# Set before launching the app
SENTRY_DSN=https://your-key@o123456.ingest.sentry.io/1234567

# For the React frontend (build-time), add to .env.production:
VITE_SENTRY_DSN=https://your-key@o123456.ingest.sentry.io/1234567

When SENTRY_DSN is not set, crash reporting is completely disabled with zero overhead. See docs/ELECTRON.md for details.

---

Documentation

Document	Description
docs/ELECTRON.md	Electron architecture, logging, and crash reporting
docs/PACKAGING.md	Build system, CI/CD, and release process
docs/UPDATE_SYSTEM.md	Auto-updater implementation
docs/sources/custom-nodes-guide.md	Custom node development

---

License

This project is licensed under the CeCILL-2.1 License. Third-party notices are listed in THIRD_PARTY_NOTICES.md, and the corresponding license texts are bundled in LICENSES/.

---

Acknowledgments

• CIRAD for supporting this research
• The nirs4all library for the NIRS analysis engine
• The open-source scientific Python and React communities

Made for the spectroscopy community