NIRScanner-Python — Minimal for Raspberry Pi 3B (Python 3.11.2)

This repository has been trimmed to the essentials required to acquire a single scan from a DLP NIRScan Nano and save the result as a CSV using Python 3.11.2 on a Raspberry Pi 3B.

Files you will use:

• NIRS.py — Python wrapper around the native _NIRScanner.so extension.
• scan_substance.py — acquisition script (per-scan 1D NumPy intensity array; optional CSV save to Data/).
• build_native_pi.sh — helper to build the native shared object with a chosen Python executable.
• requirements.txt — Python packages required by the acquisition script.
• prune_unused.sh — optional script to remove demo/test files locally on the Pi to minimize repo footprint.
• systemd/nirscan.service — example systemd unit (edit paths to your venv/project).

Quick minimal setup (assumes you already have a tflite venv and want to reuse it)

1. Copy or clone this repo to your Pi and change to the project directory.

2. Ensure a matching _NIRScanner.so is available in project root. To build it with your venv Python:

# run the build helper and give it the venv python executable
./build_native_pi.sh /path/to/venv/bin/python

3. Activate your existing venv and install dependencies:

source /path/to/venv/bin/activate
pip install -r requirements.txt

4. (Optional) Minimize repository on the Pi by removing demo/test files. Run this from the project root:

chmod +x prune_unused.sh
./prune_unused.sh

5. Run a scan and save CSV (use the venv python directly):

/path/to/venv/bin/python scan_substance.py --save-csv

6. (Optional) Run a scan and save as training data. Run this and replace "sugar" with your substance label. This will append that label to the csv file as a prefix:

/path/to/venv/bin/python python scan_substance.py --save-csv --prefix sugar

7. To run at boot, adapt the example in systemd/nirscan.service (edit ExecStart and WorkingDirectory to match your venv and project paths), then copy it to /etc/systemd/system/ and enable it:

sudo cp systemd/nirscan.service /etc/systemd/system/nirscan.service
sudo systemctl daemon-reload
sudo systemctl enable --now nirscan.service
sudo journalctl -u nirscan.service -f

Notes

• Keep lib/ and src/ if you want to try prebuilt binaries or rebuild the native extension locally — build_native_pi.sh will compile against the provided Python executable.
• prune_unused.sh will prompt before deleting demo files; I left deletion under your control so you can verify everything on the Pi first.
• If _NIRScanner.so is not compatible with the venv Python (ABI mismatch), build with the venv python as shown above.

Quick setup

1. Ensure the compiled Python extension (_NIRScanner.so) matching your Python version is available in the project root or on PYTHONPATH. The lib/ folder contains prebuilt binaries for some platforms.

2. Install OS packages (Debian/Ubuntu/Raspbian):

sudo apt-get update
sudo apt-get install -y libudev-dev libusb-1.0-0-dev python3-dev python3-pip

3. (Optional) Create a virtualenv and install Python deps used by examples:

python3 -m venv .venv
.\\.venv\\Scripts\\activate    # Windows (if testing on Windows)
source .venv/bin/activate    # Linux / Raspberry Pi
pip install numpy pandas scipy pillow requests

• If there is no _NIRScanner.so matching your Python ABI in lib/, build the native extension using the included helper script:

# example: explicitly provide python executable
./build_native_pi.sh /usr/bin/python3.11
# or use default python3 on the Pi
./build_native_pi.sh

The build script will run CMake and Make in the src/ folder and copy the resulting shared object to the project root as _NIRScanner.so.

Install Python dependencies into your venv (use the provided requirements.txt):

source .venv/bin/activate
pip install -r requirements.txt

Running a substance scan (example)

• scan_substance.py is an example script that:
  • Instantiates the NIRS wrapper
  • Configures the device
  • Performs a scan
  • Returns scan information and saves a timestamped CSV to Scans/

Example command (on the Pi):

python3 scan_substance.py --save-csv

Output:

• The script prints a short summary to stdout (intensity shape, sample info) and saves a CSV to ~/Scans/ (or Scans/ in earlier docs). The filename is either <timestamp>.csv or <prefix>-<timestamp>.csv when --prefix is provided.

• CSV layout: the saved file uses the legacy column layout expected by downstream training code. Columns (in this order) are:

  • header_version
  • scan_name
  • scan_time
  • temperature_system
  • temperature_detector
  • humidity
  • pga
  • wavelength
  • intensity
  • reference
  • valid_length
  • absorbance (computed as -log10(intensity/reference) when reference is available; otherwise NaN)

• The CSV is written with pandas.DataFrame.to_csv(...) and currently includes the DataFrame index as the first column (to preserve legacy formatting). If you prefer no index column, run the script and I can change the code to write index=False.

• Example commands:

python scan_substance.py --save-csv            # saves ~/Scans/<timestamp>.csv
python scan_substance.py --save-csv --prefix sugar   # saves ~/Scans/sugar-<timestamp>.csv

• To read the CSV with pandas:

import pandas as pd
df = pd.read_csv('~/Scans/sugar-20251210...csv')
print(df.columns)

• Keep your substance-specific models separate from the scanner wrapper. Use scan_substance.py as the acquisition step and then pipe the returned 1D array into your analysis pipeline.

License & Notes

• This repo wraps vendor-provided binaries and code; check the original project and vendor licenses for redistribution constraints.