Endoscopy Out of Body Detection #

Authors: Holoscan Team (NVIDIA)
Supported platforms: x86_64, aarch64
Language: C++
Last modified: May 13, 2025
Latest version: 1.0
Minimum Holoscan SDK version: 1.0.3
Tested Holoscan SDK versions: 2.9.0
Contribution metric: Level 1 - Highly Reliable

Endoscopy Out of Body Detection Workflow

Overview#

This application performs real-time detection of whether an endoscope is inside or outside the body during endoscopic procedures. For each input frame, the application:

Classifies the frame as either "in-body" or "out-of-body"
Provides a confidence score for the classification
Outputs either to the console or to a CSV file (when analytics is enabled)

Note: This application does not include visualization components.

Quick Start#

Run the following command to build and launch the application on a supported Holoscan platform:

./holohub run endoscopy_out_of_body_detection --language cpp

Prerequisites#

NVIDIA Holoscan SDK (version 0.5 or higher)
A supported Holoscan platform or workstation with a CUDA-capable NVIDIA GPU
CMake build system
FFmpeg (for data conversion)

Data Requirements#

Model and Sample Data#

The endoscopy detection model and sample datasets are available on NGC. The package includes:

Pre-trained ONNX model for out-of-body detection: out_of_body_detection.onnx
Sample endoscopy video clips (MP4 format): sample_clip_out_of_body_detection.mp4

Data Preparation (optional)#

The application requires the input videos to be converted to GXF tensor format. This conversion happens automatically during building, but manual conversion can be done following these steps:

Download and extract the data:
```
unzip [NGC_DOWNLOAD].zip -d <data_dir>
```

Convert the video to GXF tensor format using the provided script:

ffmpeg -i <INPUT_VIDEO_FILE> -fs 900M -pix_fmt rgb24 -f rawvideo pipe:1 | \
python convert_video_to_gxf_entities.py --width 256 --height 256 --channels 3 --framerate 30

Note: The conversion script (convert_video_to_gxf_entities.py) is available in the Holoscan SDK repository.

Organize the data directory as follows:

data/
└── endoscopy_out_of_body_detection/
  ├── LICENSE.md
  ├── out_of_body_detection.onnx
  ├── sample_clip_out_of_body_detection.gxf_entities
  ├── sample_clip_out_of_body_detection.gxf_index
  └── sample_clip_out_of_body_detection.mp4

Configuration#

The application uses endoscopy_out_of_body_detection.yaml for configuration. Key settings include:

Input video parameters in the replayer section
Model parameters in the inference section
Analytics settings for data export

Building and running the application#

./holohub run endoscopy_out_of_body_detection --language cpp

It builds and starts a Docker container, and then builds and runs the application inside the container.

For more information, see the Holohub README.md.

Running in development mode#

You can also run the application with customized arguments, you can use Holohub CLI for creating and starting the Holohub container, and then building and running the application inside the container as follows:

Create and start the Holohub container:

./holohub run-container endoscopy_out_of_body_detection

Build the application:

Once in the docker container, you can build the application by running the following command:
```
./holohub build endoscopy_out_of_body_detection --language python
```

Run the application:

After building the application, you can run it from your build directory with the following command for the basic usage and can modify the arguments as needed:

applications/endoscopy_out_of_body_detection/endoscopy_out_of_body_detection \
  --config endoscopy_out_of_body_detection.yaml \
  --data ../data/endoscopy_out_of_body_detection

Analytics Mode#

To enable analytics and export results to CSV:

Set enable_analytics: true in the configuration file:

# endoscopy_out_of_body_detection.yaml
enable_analytics: true

Configure analytics output (optional):

# Set output directory (default: current directory)
export HOLOSCAN_ANALYTICS_DATA_DIRECTORY="/path/to/output"

# Set output filename (default: data.csv)
export HOLOSCAN_ANALYTICS_DATA_FILE_NAME="results.csv"

The application will create:

A directory named after the application
Subdirectories with timestamps for each run
CSV files containing frame-by-frame classification results

Output Format#

Console Mode: Displays "Likely in-body" or "Likely out-of-body" along with confidence scores for each frame.
Analytics Mode: Outputs a CSV file with frame-by-frame classification results in the following format:

In-body,Out-of-body,Confidence Score
1,0,0.972432
1,0,0.902066

Endoscopy Out of Body Detection#