Developing Engines for VentOCR

1. VentOCR Architecture Overview

VentOCR consists of three major layers:

• Web interface (Flask)
• Analysis controller (Main.py)
• Engine modules

The web interface allows users to upload videos, select engines, and review results. The analysis controller manages execution flow, and each engine implements the logic needed to interpret a specific ventilator monitor layout.

2. Main Analysis Flow

User uploads a video
        ↓
Video registered in database
        ↓
User selects Engine
        ↓
Main.py launches analysis
        ↓
Engine module is loaded dynamically
        ↓
Video is split into smaller segments
        ↓
Frames are extracted from each segment
        ↓
Engine performs OCR and waveform detection
        ↓
Results are merged into CSV files
        ↓
Engine performs post-processing
        ↓
Results archived and shown in the web interface

During execution, the selected engine is loaded dynamically through Python imports. In practice, the analysis controller expects the engine to provide the required interface for OCR and post-processing.

Engine = mc.load_engine(engine_name)

initial_ocr(...)
post_ocr(...)

3. Engine Directory Structure

Each engine should be placed under the Engine directory using a consistent structure.

Engine/<engine_key>/
    core.py
    schema.py
    engine_options.json
    layout.jpg
    README.md

Example:

Engine/nava_ventocr/
    core.py
    schema.py
    engine_options.json
    layout.jpg
    README.md

The directory name must match the Engine Key registered in the database.

4. Required Engine Components

5. Engine Validation Rules

To keep the system stable, each engine should pass a validation step before activation.

Required Files

core.py
schema.py
engine_options.json
layout.jpg
README.md

Python Module Validation

import Engine.<engine_key>.core
import Engine.<engine_key>.schema

Required Functions

initial_ocr()
post_ocr()

Schema Validation

schema.py must define ENGINE_SETTINGS_SCHEMA as a Python dictionary.

Configuration File Validation

engine_options.json must contain valid JSON.

Documentation Requirement

Every engine should describe supported devices, expected layout, algorithm concept, and known limitations.

6. Engine Registration

After preparing the files, the engine must be registered in the VentOCR database.

INSERT INTO Engine (
Engine_Key,
Display_Name,
Developer_Name,
Ventilator_Family,
Layout_Description
)
VALUES (
'nava_ventocr',
'NAVA',
'VentOCR Developer Team',
'Servo',
'This engine analyzes four waveforms including the Edi waveform.'
);

7. Minimal Engine Template

A minimal engine does not need to solve waveform analysis perfectly. It only needs to satisfy the required interface and return valid structures.

Minimal core.py

import pandas as pd

def initial_ocr(grayed_frame, total_frames, subfolder, engine_options):
    rows = []
    for i in range(total_frames):
        rows.append({
            "Frame": i + 1,
            "X": i,
            "Pressure": None,
            "Flow": None,
            "Volume": None,
            "Edi": None
        })
    return pd.DataFrame(rows)

def post_ocr(df, analyze_id, user_id, engine_options):
    df_frames = df.copy()

    df_breaths = pd.DataFrame([
        {
            "BreathNumber": 1,
            "Start_Frame": 1,
            "End_Frame": len(df_frames),
            "PVA": ""
        }
    ])

    return df_frames, df_breaths

Minimal schema.py

ENGINE_SETTINGS_SCHEMA = {
    "General": {
        "threshold": {
            "label": "Detection Threshold",
            "type": "float",
            "default": 0.5
        },
        "use_filter": {
            "label": "Use Noise Filter",
            "type": "bool",
            "default": True
        }
    }
}

Minimal engine_options.json

{
  "General": {
    "threshold": 0.5,
    "use_filter": true
  }
}

Minimal README.md

# Example Engine

## Supported Devices
- Example ventilator monitor

## Expected Layout
- Four waveform rows
- Pressure / Flow / Volume / Edi

## Description
This is a minimal template engine for VentOCR.

## Limitations
This engine is only a structural example and does not implement real detection logic.

8. Tips for Engine Developers

• Keep your engine independent from hard-coded external paths.
• Use vectorized operations when waveform processing becomes expensive.
• Test on short clips first to reduce iteration time.
• Document the expected monitor layout clearly.
• Keep raw extraction and post-processing separated.

9. Future Engine Ecosystem

The long-term goal of VentOCR is to support an ecosystem where researchers and engineers can publish engines for different ventilator models and waveform layouts.

By separating engine implementation from the core platform, VentOCR can evolve without tightly coupling every new algorithm to the main application.