simplevision

Run SimpleVision computer-vision pipelines from Python.

SimpleVision is a learning tool for students: you build a vision pipeline visually in the desktop editor (threshold, blob detect, color match, geometric match, OCR, …), tick the measurements you care about, and the editor saves the pipeline as a single .simplevision JSON file. This library is the companion that runs that pipeline from Python so you can plug the measurements into your own code.

Install

pip install simplevision

OCR is optional (it pulls in RapidOCR + ONNX Runtime, ~300 MB):

pip install "simplevision[ocr]"

Use it

Open your pipeline in the SimpleVision editor, tick the measurements you want in Output Control, and save. Then in Python:

from simplevision import Pipeline

p = Pipeline.load("my_pipeline.simplevision")
p.run()

# Each name below is one you typed in the editor's Output Control panel.
if p.outputs.MatchPercentage[0] > 0.85:
    print("Match found at", p.outputs.Centroids[0])

Pass your own frame to p.run() to process many images through the same pipeline:

import cv2
for path in ["frame_001.png", "frame_002.png", "frame_003.png"]:
    p.run(path)
    print(path, "->", p.outputs.Count)

print(p.outputs) shows everything readably — handy while you're getting oriented.

Live graph loops

A graph with a webcam Load node keeps the camera open between runs and processes the newest frame. Use a context manager to release the camera when you finish or interrupt the loop:

from simplevision import Graph

try:
    with Graph.load("main.simplevision") as graph:
        while True:
            graph.run()
            print(graph.outputs)
except KeyboardInterrupt:
    pass

You can also call graph.close() in a finally block. Passing an explicit image to graph.run(image) releases any webcam previously opened by that graph. The first webcam run includes camera startup; subsequent runs reuse the stream and discard old frames while image processing runs.

Pattern Match: scale and rotation

In the editor, open Pattern Match → Settings and enable Search different sizes and/or Search different angles. Save the project after changing the ranges; Graph.load(...).run() and Pipeline.load(...).run() use those same settings. Existing projects keep both searches off.

Scale is a percentage of the saved template: 50% is half-size, 100% is the original, and 150% is one and a half times the size. Angles are degrees; positive values turn counterclockwise. Both endpoints are included, along with 100% and 0° when those values lie within the chosen ranges.

For a first trial, use scale 50–150% in steps of 10% and rotation −30–30° in steps of 10°. Wider ranges and smaller steps take longer; searches are limited to 256 size/angle combinations. Size changes and rotation within the image are covered, but perspective tilt is not corrected.

The existing Count, Scores and Positions outputs include the combined matches, with duplicate detections suppressed across sizes and angles. Output Control also offers Angles and Scales, in the same best-score-first order. Scales are factors (1.5 means 150%), while Angles are degrees. The viewer shows each match's rotated outline, score, scale and angle.

What's in the package

• simplevision.Pipeline, simplevision.Outputs, simplevision.Point — the student-facing API.
• simplevision.runtime — the execution engine. You normally don't import this directly; the desktop app uses it as a sidecar and Pipeline.run() drives it under the hood. The runtime is documented in docs/pipeline-spec.md if you want to build pipelines without the editor.

License

Apache-2.0. See LICENSE and NOTICE.