MojoScale Studio Docs
API Reference

cv

Computer vision and ESP-DL model module.

All modules Open Studio
Studio Docs Vision & AI

import cv

The cv module loads the single ESP-DL model stored in the firmware ai_model flash partition and exposes model lifecycle, metadata, profiling, and camera inference helpers.

Quick example

import cv

cv.load("hand_gesture_recognition")
result = cv.run_camera("predict")
if result["ok"]:
    print(result["label"])

importcv

Computer vision and ESP-DL model module.

The cv module loads the single ESP-DL model stored in the firmware ai_model flash partition and exposes model lifecycle, metadata, profiling, and camera inference helpers.

API 12 available

cv.load(model_name: str) -> bool

Load the installed AI model and make it ready for inference.

import cv

cv.load("hand_gesture_recognition")
Parameter

model_name str, required

Model ID of the model installed on this device.

Returns

bool

True when the model was loaded successfully.

Note

Only one AI model is stored on the device at a time. Install or change the model from Studio before calling cv.load(...).

Load can fail when
  • No model is installed.
  • model_name does not match the installed model.
  • The model data is invalid.
  • There is not enough free memory.
View available models
Model Task Size What it recognizes
cat_detect Cat Detect Detect 487 KB Cat detector for ESP32-S3 camera input.
dog_detect Dog Detect Detect 488 KB Dog detector for ESP32-S3 camera input.
face_detect Face Detect Detect 469 KB Human face detector for ESP32-S3 camera input.
hand_detect Hand Detect Detect 486 KB Hand detector for ESP32-S3 camera input.
hand_gesture_recognition Hand Gesture Recognition Predict 769 KB Hand gesture classifier for ESP32-S3 camera input.
pedestrian_detect Pedestrian Detect Detect 425 KB Pedestrian detector for ESP32-S3 camera input.
Example
if not cv.load("hand_gesture_recognition"):
    print("Model failed to load")

cv.unload() -> any

Unload the current ESP-DL model and free its memory.

Returns

any Native unload result.

cv.loaded() -> bool

Return whether a model is currently loaded.

Returns

bool True when cv has an active ESP-DL model.

cv.test() -> bool

Run ESP-DL embedded test vectors for the loaded model.

Returns

bool True when ESP-DL model self-test passes.

cv.profile(sort_by_latency: bool = None) -> any

Print ESP-DL memory and module latency profiling to firmware logs.

Parameters
Name Type Pass as Required Description
sort_by_latency bool positional or keyword No Optional boolean to sort module profiling by latency.
Returns

any Native profile result.

cv.profile_memory() -> any

Print ESP-DL memory profiling to firmware logs.

Returns

any Native profile result.

cv.profile_module(sort_by_latency: bool = None) -> any

Print ESP-DL module latency profiling to firmware logs.

Parameters
Name Type Pass as Required Description
sort_by_latency bool positional or keyword No Optional boolean to sort modules by latency.
Returns

any Native profile result.

cv.metadata(key: any) -> str

Read a metadata property from the loaded ESP-DL model.

Parameters
Name Type Pass as Required Description
key any positional or keyword Yes Metadata property key.
Returns

str Metadata property value as a string.

cv.predict_camera(top_k: int = None, score_threshold: float = None) -> dict

Capture a camera frame and run it through the loaded image model.

The firmware always returns a map. On success, the map contains: ok: True. label: Top predicted label. Gesture models use labels like "one", "five", "ok", "no_gesture", and "no_hand". score: Top prediction score after softmax. predictions: Compact top-k string such as "five:0.9878, ok:0.0031, no_hand:0.0031". count: Number of returned predictions. class_count: Number of output classes. frame_width/frame_height/frame_len: Captured frame information. input_width/input_height: Model input image size. capture_ms/preprocess_ms/model_ms/postprocess_ms/total_ms: Timing information. On failure, the map contains: ok: False. error: Human-readable error string.

When to use predict

Use prediction models when the frame should produce one best label, such as a gesture or classification result.

Result shape

label str

The top class returned by the model.

score float

Confidence score for the top label.

Typical checks

ok and count

Check these before reading label or score.

Example
result = cv.predict_camera(top_k=1, score_threshold=0.30)

if result["ok"] and result["count"] > 0:
    label = result["label"]
    score = result["score"]
    print(label)
    print(score)
Parameters
Name Type Pass as Required Description
top_k int positional or keyword No Optional number of predictions to return. Defaults to 3.
score_threshold float positional or keyword No Optional minimum score for returned predictions. Defaults to 0.0.
Returns

dict Map-like prediction result.

cv.detect_camera(top_k: int = None, score_threshold: float = None, nms_threshold: float = None) -> dict

Capture a camera frame and run detector postprocessing on the loaded image model.

Supported detector outputs are ESP-DL Pico/ESPDET-style models with score/box tensor stages. On success, the map contains: ok: True. task: "detection". postprocess: Detector postprocessor route, such as "pico", "espdet", or "yolo11". detections: List of detection maps. Each item contains label, class_id, score, x, y, w, h, x1, y1, x2, y2. detections_text: Compact string such as "face:0.9123@[42,30,120,118]". count: Number of detections after thresholding and NMS. candidate_count: Number of candidates before NMS. class_count: Number of detector classes. threshold/nms_threshold: Thresholds used for the result. frame_width/frame_height/frame_len: Captured frame information. input_width/input_height: Model input image size. capture_ms/preprocess_ms/model_ms/postprocess_ms/total_ms: Timing information. On failure, the map contains: ok: False. error: Human-readable error string.

When to use detect

Use detection models when the frame can contain zero, one, or many objects and you need boxes around them.

Result shape

detections list

Each detection includes label, score, x, y, w, and h.

detections_text str

Compact text for quick printing.

Typical checks

ok and count

Check these before reading detection boxes.

Example
result = cv.detect_camera(top_k=5, score_threshold=0.50)

if result["ok"] and result["count"] > 0:
    print(result["detections_text"])
Parameters
Name Type Pass as Required Description
top_k int positional or keyword No Optional maximum detections to return. Defaults to 10.
score_threshold float positional or keyword No Optional minimum score. Defaults to 0.50.
nms_threshold float positional or keyword No Optional IoU threshold for non-max suppression. Defaults to 0.45.
Returns

dict Map-like detection result.

cv.run_camera(type: str, top_k: int = None, score_threshold: float = None, nms_threshold: float = None) -> dict

Convenience wrapper that runs prediction or detection from one method. The route is not auto-detected from the model.

Parameters
Name Type Pass as Required Description
type str positional Yes Required route. Use "predict" for classification or "detect" for detection; Studio does not infer this from the loaded model.
top_k int positional or keyword No Optional prediction/detection count.
score_threshold float positional or keyword No Optional score threshold.
nms_threshold float positional or keyword No Optional detection-only NMS threshold.
Returns

dict Map-like result from predict_camera or detect_camera.

cv.info() -> dict

Return cv module status and memory information.

Returns

dict Map-like value with partition, partition_size, loaded, model_name, heap_free, and psram_free.