Troubleshooting#

Error: “virtual environment not found”#

Run .\setup.ps1 from the ultrasound-ovarian-segmentation folder first. It creates venv and installs requirements.txt.

PowerShell blocks the scripts#

Allow scripts for the current session only:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Error: “model IR not found: models\ds2net_segformer_b5_256\model.xml”#

The application does not include a model. Either drop in a prebuilt Intermediate Representation (IR) or produce one:

  • Prebuilt IR — if you have the exported model.xml and model.bin (for example, from another box), place both under models\ds2net_segformer_b5_256\. That is all the application needs to run.

  • Produce it:

    .\prepare_model.ps1 -Verify          # export an existing checkpoint
.\prepare_model.ps1 -Train -Verify   # or train first

See Model Preparation for details.

Device not available or falls back to CPU#

If --device GPU is not among the available devices of the OpenVINO™ Toolkit (OpenVINO™), the application logs a warning and falls back to CPU. Check that:

  • Intel graphics drivers are installed and current.

  • The device appears in Task Manager and venv\Scripts\python.exe -c "import openvino as ov; print(ov.Core().available_devices)" lists GPU.

Note

NPU: neither model (DS2Net or SAM) is supported on the NPU. Passing --device NPU logs a notice and uses the GPU (or CPU) instead.

No pop-up window appears#

  • Make sure OpenCV has GUI support: requirements.txt installs opencv-python (not opencv-python-headless). A headless build renders no window. Verify with venv\Scripts\python.exe -c "import cv2; print(cv2.getBuildInformation())" and look for a GUI backend (e.g., WIN32UI).

  • Run from an interactive desktop session (not a service or SSH-only session).

  • Check the console for a source or device error that prevented the run from starting.

Mean Dice is ~0 after export#

The most likely causes are:

  • The IR was exported without --from-pretrained (random weights). Re-run:

    venv\Scripts\python.exe -m backend.bootstrap.export ^
    --from-pretrained models\segformer_b5_mmotu --res 256

  • --res does not match the resolution the IR was exported at.

  • Dataset paths are wrong — eval.py could not find images/ or annotations/ under --data, or val.txt lists the wrong stems.

SAM architecture: IR not found or low Dice#

With -Arch sam, the application loads three IRs (YOLO bounding box, SAM encoder, SAM decoder). If any is missing, prepare them and confirm the stock SAM ViT-B weights were downloaded to models\sam_vit_b_01ec64.pth first:

.\prepare_model.ps1 -Arch sam -Verify

A low end-to-end Dice (well under 0.82) usually means the encoder IR was exported from random weights (missing --weights models\sam256_stockft.pth) or the encoder was fine-tuned with the wrong preprocessing. The fine-tune and the runtime must both scale images by /255 (no mean or standard deviation normalization). See Model Preparation.

SAM training runs on CPU — how to use the iGPU#

.\prepare_model.ps1 -Arch sam -Train trains on the Intel iGPU by default (-TrainDevice GPU → PyTorch xpu) for both the YOLO detector and the encoder fine-tune. To force CPU, pass -TrainDevice CPU. If training still falls back to CPU with -TrainDevice GPU, the PyTorch build in venv has no Intel XPU support. Verify with:

venv\Scripts\python.exe -c "import torch; print(hasattr(torch,'xpu') and torch.xpu.is_available())"

If this prints False, install a PyTorch build with Intel XPU support (or run on CPU with -TrainDevice CPU, which is slower). -TrainDevice selects the training device (default GPU) and is separate from -Device, which selects the OpenVINO™ evaluation/runtime device. The runtime/export device name is the OpenVINO™ GPU; the training device name is the PyTorch xpu — they are not interchangeable.

GPU KPI prints “OVER”#

This is unexpected on typical ultrasound workloads (the pipeline is host-bound, utilizing ~12–24% iGPU). If you see OVER, the device was saturated by other work, or the governor was disabled (--no-governor). Re-run without --no-governor, or lower --gpu-cap to further pace inference down.

GPU HUD shows “unavailable” or “governor inactive”#

The governor reads Windows GPU-Engine performance counters via pywin32. If pywin32 is missing, or you run on a non-Windows machine, the governor becomes inactive and the HUD marks GPU utilization unavailable — the application still runs. On Windows, reinstall dependencies: .\setup.ps1.

Webcam opens the wrong camera#

--input is the device index. Try 0, 1, or 2. Close other applications that may hold the camera.

Web dashboard: page does not load#

  • Confirm the server is running: the console prints [webapp] serving on http://127.0.0.1:8080. Open that exact URL.

  • If the port is busy, start on another port: .\run_webapp.ps1 -Port 8090.

  • A blank page usually means the prebuilt UI (webapp\ui\dist) is missing. .\run_webapp.ps1 builds it automatically on the first launch — this needs Node.js 18+ on PATH — then reuses it on later runs. If the page stays blank, confirm Node.js is installed and re-run .\run_webapp.ps1 so it can rebuild, or build the UI manually: cd webapp\ui; npm install; npm run build.

Web dashboard: Start fails with “input not found”#

Enter a valid path in Video / image source (a .mp4 file or a folder of frames), or leave the field blank to use the data\OTU_2d\images dataset you prepared during model preparation. The path is resolved on the machine running the server.

Web dashboard: “HW monitoring: DISABLED”#

The browser still shows CPU and memory (via psutil), but the iGPU, NPU, and power graphs need the Intel vendor tools and their Python dependencies:

  • Install pandas and pywin32 into the venv.

  • Copy the vendor tools from your benchmark install into this clone’s monitoring\tools: SoCWatch (drives the power chart) and Level Zero (drives the NPU chart). They are independent — copy either or both; whichever you omit simply shows as unavailable while every other metric keeps working.

These are intentionally not committed (≈139 MB of vendor binaries). Without them, the pipeline and its latency, FPS, and iGPU KPIs still work.