fundus-camera-watchdog 1.0.0

Prerequisites

1. A running clinicedc server with edc-retinopathy installed and an API token created.

2. The camera software must write its output into the watched folder using the expected layout (see Folder layout below).

Folder layout

The camera creates one subfolder per subject. Folder names follow a configurable pattern (see subject_folder_pattern). Filenames contain the eye laterality (OD for right, OS for left), extracted via filename_eye_pattern.

Combined report (default):

C:\RetCamOutput\
    105-10-0989-3_\
        105-10-0989-3_Retina_OD_20260602_121802.jpg
        105-10-0989-3_Retina_OS_20260602_121803.jpg
        105-10-0989-3_Retina_OD_20260602_121802.dcm
        105-10-0989-3_Retina_OS_20260602_121803.dcm
        105-10-0989-3_Report_20260602.html
    105-10-0001-2_\
        ...

Per-eye report:

C:\RetCamOutput\
    105-10-0989-3_\
        105-10-0989-3_Retina_OD_20260602_121802.jpg
        105-10-0989-3_Retina_OS_20260602_121803.jpg
        105-10-0989-3_Report_OD_20260602.html
        105-10-0989-3_Report_OS_20260602.html

Processing is triggered once a subject folder contains the expected number of files:

• Combined (default): at least 2 DICOM and 1 HTML file.

• Per-eye: at least 2 DICOM and 2 HTML files.

By default only DICOM files are uploaded. JPEG files are ignored unless --include-jpgs is set. HTML reports can be made optional with --no-require-html.

Quick start

1. Generate a sample config in the camera output folder:

   cd C:\RetCamOutput
   uvx fundus-camera-watchdog --create-config

   This creates fundus_camera_watchdog.json with sensible defaults.

2. Edit the config to fill in api_url, subject_folder_pattern, and optionally filename_eye_pattern, device_id, etc.

3. Set the API token as an environment variable (recommended):

   REM Windows (persists across reboots)
   setx FUNDUS_CAMERA_WATCHDOG_TOKEN "YOUR_DRF_TOKEN"

4. Start the watchdog:

   cd C:\RetCamOutput
   uvx fundus-camera-watchdog

Configuration

Settings are resolved in the following order (highest priority first):

1. CLI flags (e.g. --api-url)

2. JSON config file

3. FUNDUS_CAMERA_WATCHDOG_TOKEN environment variable (token only)

4. Built-in defaults

{
    "watch_dir": "C:\\RetCamOutput",
    "api_url": "https://edc.example.com",
    "device_id": "RET-CAM-001",
    "site_id": "40",
    "report_type": "combined",
    "subject_folder_pattern": "^(?P<subject_identifier>\\d{3}-\\d{2}-\\d{4}-\\d)_$",
    "filename_eye_pattern": "(?P<eye>OD|OS)"
}

Usage

Run from the camera output folder:

cd C:\RetCamOutput
uvx fundus-camera-watchdog

With an explicit config file:

uvx fundus-camera-watchdog --config C:\path\to\fundus_camera_watchdog.json

CLI flags override any value from the config file:

uvx fundus-camera-watchdog --log-level DEBUG --report-type per_eye

Without a config file:

uvx fundus-camera-watchdog ^
    --watch-dir C:\RetCamOutput ^
    --api-url https://edc.example.com ^
    --token YOUR_TOKEN ^
    --device-id RET-CAM-001 ^
    --subject-folder-pattern "^(?P<subject_identifier>\d{3}-\d{2}-\d{4}-\d)_$"

Stop with Ctrl+C.

What it does

The watchdog runs continuously and performs the following for each subject:

1. Detect – watches for new files in subject subfolders using filesystem events (watchdog), plus a periodic sweep every 60 seconds as a safety net.

2. Wait – each file is given up to 30 seconds to stabilise (stop growing) before being registered.

3. Classify – extracts eye laterality from each filename using the configured pattern. Maps files to API types:

   • *.dcm + OD -> right_dicom

   • *.dcm + OS -> left_dicom

   • *.jpg + OD -> right (only with --include-jpgs)

   • *.jpg + OS -> left (only with --include-jpgs)

   • *.html (combined) -> report

   • *.html + OD (per_eye) -> right_report

   • *.html + OS (per_eye) -> left_report

4. Resolve – POST /api/retinopathy/resolve/ confirms an EyeExamRegister exists on the server for this subject. If the server answers no_eligible_session, every register for the subject is complete or contraindicated and no upload can succeed until someone creates a new one in the EDC, so the subject folder is set aside (see Rejected subjects below) rather than retried.

5. Upload – sends each file to the server. Original filenames are preserved. Each upload includes a SHA-256 checksum. Multiple files per eye are supported. By default only DICOM and HTML files are uploaded; use --include-jpgs to also upload JPEG images.

6. Verify – GET .../status/ confirms the session received the expected files.

7. Archive – the subject folder is moved to <watch-dir>/processed/<subject_id>_<timestamp>/.

Error handling

• Retries – every API call is retried up to 3 times with a 5-second delay.

• Failed subjects – if any step fails, the subject is left in place and retried on the next 60-second sweep.

• Rejected subjects – if the server reports that no register can accept the upload (no_eligible_session), retrying cannot help. The subject folder is moved to <watch-dir>/rejected/<subject_id>_<timestamp>/ and an error is logged naming the subject. Create a new entry in the Eye Exam Register in the EDC, then move the folder back under the watch directory to upload it.

• Startup scan – on (re)start the watchdog scans all existing subject folders, picking up where it left off.

• Thread safety – file detection and upload run on separate threads with proper locking.