File: nedc_dpath_demo/AAREADME.txt
Tool: The NEDC DPATH Demo System
Version: 1.0.0

-------------------------------------------------------------------------------
Change Log:

20251217 (DH): initial demo system version

-------------------------------------------------------------------------------
Overview

This tool is a lightweight demo of a DPATH workflow intended for interactive
exploration and annotation review.

Directory overview (typical):
  AAREADME.txt
  bin/    command line entry points
  docs/   help, usage, and parameter files
  lib/    python modules used by the tools
  models/ shipped demo model weights
  src/    source tree and Makefiles
  test/   small example inputs (sanity checks)

+ Note:

  This demo distribution is intentionally scoped to support interactive use.
  It does not provide end-to-end pipeline components such as:
   - pre-processing pipelines
   - training
   - evaluation / scoring

--------------------------------------------------------------------------------
 Hackel, D., Bagritsevich, M., Dumitrescu, C., Al Mamun, Md. A., Purba,
 S. A., Heathcote, D., Obeid, I., & Picone, J. (2026). Enabling
 Microsegmentation: Digital Pathology Corpora for Advanced Model
 Development. In Signal Processing in Medicine and Biology: Applications
 of Artificial Intelligence in Medicine and Biology (Vol. 1, p. 50).
 Springer.

A. WHAT'S NEW

Version 1.0.0:

  + Initial version, includes slide viewing gui with a decoder
    and post processor attached
  + various customization options in the edit menu

B. INSTALLATION REQUIREMENTS

Python code unfortunately often depends on a large number of add-ons, making
it very challenging to port code into new environments. This tool has been
tested extensively on Windows and Mac machines running Python v3.11.x.

Software tools required include:

 o Python 3.11.12
 o Numpy (1.26.4): https://numpy.org/
 o Pillow (10.2.0): https://pillow.readthedocs.io/en/stable/
 o Torch (2.2.2): https://pytorch.org/
 o Torchvision (0.17.2): https://pytorch.org/vision/stable/
 o SciPy (1.14.1): https://scipy.org/
 o lxml (5.3.0): https://lxml.de/
 o Shapely (2.1.2): https://shapely.readthedocs.io/
 o OpenCV-Python (4.10.0.84): https://pypi.org/project/opencv-python/
 o Pillow-HEIF (0.22.0): https://pypi.org/project/pillow-heif/
 o OpenSlide-Python (1.4.2): https://pypi.org/project/openslide-python/
 o OpenSlide-Bin (4.0.0.8): https://pypi.org/project/openslide-bin/
 o cuCIM-cu12 (25.4.0): https://docs.rapids.ai/api/cucim/stable/

There is a requirements.txt included in the release that helps you automate
the process of updating your environment.

C. USER'S GUIDE

Please use light mode in your system settings, as some buttons may not be visible in dark mode.

C.1. WINDOWS USERS


For Window users, we recommend users to create a virtual environment with venv.(https://docs.python.org/3/library/venv.html)

We can create a virtual environment with this command:

 $ py -3.11 -m venv /path/to/new/virtual/environment
(python version should be 3.11.x)

Once the environment has been created, you need to do the following things if
you want to run this from any directory:

 1./ Activate your venv environment

    If you are using cmd.exe: 
	$ <venv>\Scripts\activate.bat

    If you are using Powershell: 
	$ <venv>\Scripts\Activate.ps1

    If successful, you should be able to see your environment name in parenthesis at the beginning of the command then followed by your current
    directory:
	Ex: (environment) PS C:\Users\foo\bar>

 2./ Installing dependencies
   
    Change directory to the root of nedc_dpath_demo(v1.0.0). You should see a requirement.txt file there.
    
    Once you are at the root of the system, please run this command to install all the needed dependencies:
     
    $ pip install -r requirements.txt

Once the software has been installed, you need to do the following things if
you want to run this from any directory:

 3./ Running the main script

    At the root of the project. Please run the main.py script located in the src directory:

    $ python .\src\main.py

    NOTE: Please use a terminal that enables GUI rendering. Microsoft Terminal is recommended.  


C.2. LINUX/MAC USERS

Before creating a virtual environment, make sure Python 3.11.x is installed on your system. 
You can verify this by running 
python3.11 --version.

1./ To create a new Python virtual environment, run:
python3.11 -m venv /path/to/virtual/environment

After the environment is created, activate it using:
source /path/to/virtual/environment/bin/activate

If activation is successful, the name of the virtual environment will appear in parentheses 
at the beginning of your terminal prompt, followed by your current directory. For example:
(environment) /home/username: $

This indicates that the virtual environment is active and ready for use.

2./ Installing dependencies
   
    Change directory to the root of nedc_dpath_demo(v1.0.0). You should see a requirement.txt file there.
    
    Once you are at the root of the system, please run this command to install all the needed dependencies:
     
    $ pip install -r requirements.txt

The easiest way to run this is to change your current working directory
to the root directory of the installation and execute the tool as follows:
 $ cd <my_install_location>/nedc_dpath_demo/v1.0.0
 $ ./bin/nedc_dpath_demo
 or
 $ python ./src/main.py

Once the software has been installed, you need to do the following things if
you want to run this from any directory:

 - set the environment variable NEDC_NFC to the root directory
   of the installation:
      $ export NEDC_NFC='<my_install_location>/nedc_dpath_demo/v1.0.0'

 - put $NEDC_NFC/bin in your path:
      $ export PATH=$PATH:$NEDC_NFC/bin

You should be able to type:

 $ which nedc_dpath_demo

and see the command. Then you can simply type:

 $ nedc_dpath_demo


===============================================================================
===============================================================================

This distribution provides a working example for interactive slide review and
processing. Recommended usage is to run the demo as-is before making changes.

The primary user-facing components are:
  + A GUI for whole-slide viewing and overlay inspection
  + A command-line decoder (also callable from the GUI) for generating CSV
    hypothesis outputs from slide inputs using the shipped EB0 model
  + A command-line post-processor (also callable from the GUI) for applying
    post-processing algorithms to decoder CSV outputs

-------------------------------------------------------------------------------
A. GUI (how to use it and basic customization)

The GUI is the main entry point for interactive viewing and running the demo.

1. Driver :: run the GUI

  $NEDC_NFC/bin/nedc_dpath_demo

2. GUI :: basic operations included

  (1) Open a slide:
      File -> Open
      Select a WSI file (for example: $NEDC_NFC/test/svs/<file>.svs)

  (2) Use view toggles as needed:
      View -> Legend
      View -> Histogram
      View -> Navigator Overlay
      View -> Heatmap
      View -> Logging

  (3) Run decoding:
      Process -> Decode

  (4) Run post-processing:
      Process -> Postprocess

3. GUI :: basic customization

  Edit -> Preferences

  Common settings include:
   - active model name (default: eb0)
   - decoder executable path (default: $NEDC_NFC/src/decoder/nedc_dpath_eb0_decode.py)
   - decoder parameter file path
   - post-processor parameter file path
   - hypothesis display threshold
   - visualization controls (opacity, edge widths, etc.)
   - performance controls (tile size, viewport margin, streaming budgets)

  Save Settings persists preferences for future runs.
  Reset Settings restores defaults.

-------------------------------------------------------------------------------
B. DECODER (stand-alone and via the GUI) + customization

The shipped decoder is:
  $NEDC_NFC/src/decoder/nedc_dpath_eb0_decode.py

1. GUI :: running the decoder through the GUI

  Use:
    Process -> Decode

  The GUI calls the decoder executable configured in Preferences and passes the
  configured decoder parameter file.

2. Driver :: running the decoder stand-alone

  python $NEDC_NFC/src/decoder/nedc_dpath_eb0_decode.py --help

  Typical usage patterns:

   (1) decode a single slide:
     python ./src/decoder/nedc_dpath_eb0_decode.py <slide.svs>

   (2) decode multiple slides:
     python ./src/decoder/nedc_dpath_eb0_decode.py <slide1.svs> <slide2.svs> ...

   (3) decode from a list file (one path per line):
     python ./src/decoder/nedc_dpath_eb0_decode.py <slides.list>

   (4) specify a parameter file:
     python ./src/decoder/nedc_dpath_eb0_decode.py -p <params.toml> <slide.svs>

   (5) specify an output directory:
     python ./src/decoder/nedc_dpath_eb0_decode.py -o <output_dir> <slide.svs>

3. Demo :: decoder parameter file

  The shipped decoder parameter file is located here:
    $NEDC_NFC/docs/params/nedc_dpath_eb0_decode_params_v00.toml

  Customize values in that file to control decoding behavior and performance.
  Make install to update docs directory (necessary)
  Common fields include:
    - frame size, window size
    - batch size, number of workers, number of threads
    - pre_process_algorithm (example: sliding_window or tissue_mask)
    - input weights path (example: $NEDC_NFC/models/model_eb0.pckl)
    - device (cpu or cuda)

4. Demo :: decoder customization locations (summary)

  You can customize decoding via:
   - GUI Preferences (recommended for most users)
   - decoder params file ($NEDC_NFC/docs/params/*.toml)

-------------------------------------------------------------------------------
C. POST-PROCESSOR (stand-alone and via the GUI) + customization

The shipped post-processor is:
  $NEDC_NFC/src/nedc_dpath_post_proc.py

It applies a post-processing algorithm to decoder CSV outputs.

1. GUI :: running the post-processor through the GUI

  Use:
    Process -> Postprocess

  The GUI uses the post-processor parameter file configured in Preferences.

2. Driver :: running the post-processor stand-alone

  python $NEDC_NFC/src/nedc_dpath_post_proc.py --help

  Typical usage patterns:

   (1) post-process a single decoder CSV:
     python ./src/nedc_dpath_post_proc.py <decode_output.csv>

   (2) post-process multiple CSV files:
     python ./src/nedc_dpath_post_proc.py <a.csv> <b.csv> ...

   (3) post-process from a list file (one path per line):
     python ./src/nedc_dpath_post_proc.py <csvs.list>

   (4) specify a parameter file:
     python ./src/nedc_dpath_post_proc.py -p <pproc_params.toml> <decode_output.csv>

   (5) specify an output directory:
     python ./src/nedc_dpath_post_proc.py -o <output_dir> <decode_output.csv>

3. Demo :: post-processor parameter file

  The shipped post-processor parameter file is typically:
    $NEDC_NFC/docs/params/nedc_dpath_post_proc_params_v00.toml

  Common fields include:
    - post-process algorithm (priority, confidence, mode, knn, dilation)
    - priority_map (label/priority map TOML)
    - threshold

4. Demo :: label map / priority map notes

  Some post-processing algorithms require a label/priority map, which is
  located in:
    $NEDC_NFC/docs/params/nedc_dpath_label_map_v00.toml

  Important:
   - a "bckg" (background) label is required
   - "bckg" must appear in both the target label map and the priority map

5. Demo :: post-processor customization locations (summary)

  You can customize post-processing via:
   - GUI Preferences (recommended for most users)
   - post-proc params file ($NEDC_NFC/docs/params/*.toml)

-------------------------------------------------------------------------------
If you have any additional comments or questions about the data or software,
please direct them to help@nedcdata.org. We will do our best to answer them.
However, this distribution is fairly complex, so familiarity with Linux, shell,
and Python is required.

Best regards,

Joe Picone
