Vision and models

How vision runs

Vision only runs while a session is started and a script uses it. Each tool, such as vision.color or vision.model, is set up by the script and reports its latest result on every frame. The vision API reference lists every tool.

GPU and CPU

Detection models run on ONNX Runtime, which is included with Atlas. It can use your graphics card through DirectML, or your processor. A script chooses with the backend argument:

DirectML works with DirectX 12 graphics cards from AMD, Intel and NVIDIA. Atlas uses the first graphics adapter Windows lists. Keep your graphics driver up to date.

Add a model

Atlas does not include a detection model. Choose the model file in your script with models.set, then pass it to vision.model, vision.person or vision.face:

models.set("C:/Atlas/Models/players.onnx");

• Use the full path to the .onnx file. A relative path is resolved against the folder Atlas was started in, which you usually don't control.
• The whole path must use only English letters, digits, spaces and common punctuation, including your Windows user folder's name. If your user folder has other characters, keep models in a folder such as C:/Atlas/Models.
• A model you get from the Library is loaded with the atlas-library:// address Atlas shows after you load it.
• Give several models their own names with models.set(name, path), and read them back with models.path.

Supported models

Atlas runs YOLOv8-style object detection models in ONNX format, such as YOLOv8 and YOLO11 exports:

• Input: one 3-channel image as a float tensor shaped [1, 3, height, width]. Models without a fixed size run at 640×640.
• Output: [1, 4 + classes, anchors].
• Atlas scales each frame to fit the model with letterboxing, merges overlapping boxes, and keeps up to 64 detections per frame.

Text, QR codes and barcodes

• vision.ocr reads one line of text made of the letters A–Z and a–z, digits, hyphens and spaces; accented letters are never returned. English is used unless the script names another language.
• To use another Tesseract language, pass its code in the script, for example vision.ocr(roi, "deu"). Then set the TESSDATA_PREFIX environment variable to the folder that contains deu.traineddata, and restart Atlas.
• vision.qr reads QR, Micro QR and rMQR codes; vision.barcode reads common 1D and 2D barcodes. Each reads up to 16 codes per frame.

If a model finds nothing

• Check that the path in models.set points to an existing .onnx file, and that the path uses only the characters described above.
• Check that the model is a YOLOv8-style detection model with the input and output shapes above.
• If you forced vision.gpu, try vision.auto or vision.cpu. If the model then works, the GPU could not load it with DirectML; update your graphics driver.
• Lower the tool's threshold (default 0.5) to see weaker detections.
• Watch the preview: Atlas draws each detection on it, so you can see what the model finds.