API 레퍼런스

Public API

class ovkit.Model(model='', source=None, /, **kwargs)

기반 클래스: object

An OpenVINO model with automatic resolution, task detection, and IO.

One name, one call — and the input can come along in the same call:

r = Model("detect", "street.jpg")     # runs now -> one Results
r = Model("얼굴분석", "group.jpg")     # Korean names work too
for r in Model("track", 0):           # webcam/video -> a stream
    ...

Or keep the model and ask it again and again, which is the same thing:

ai = Model("얼굴분석")                 # no input -> a reusable object
ai("group.jpg")                       # -> one Results, as above
ai("우리반/")                          # a folder  -> a list
for r in ai(0):                       # a webcam  -> a stream
    ...

The shape follows the input, not which of the two forms you used. A photo, a sound file or a sentence answers with one Results; a folder or a list answers with a list; a webcam index, a video file or "mic" answers with a stream that opens when you start iterating.

How many things were found is a different question, and it lives inside the result: ten people in one photo is still one Results, with ten entries in r.found.

predict() is the uniform form underneath — always a list, or a generator with stream=True. Library code should call that.

Capability names (face_analyze, read_text, track, gaze, …) build a Pipeline that chains the models the answer needs. They behave exactly like a model: same sources, same Results. ovkit.list_pipelines() lists them.

매개변수:

• model (str | Path) – A registered model name ("rtdetr_r50"), a capability name ("face_analyze"), or a path to an IR .xml / .onnx file.

• task – Override task auto-detection ("detect"/"classify"/…).

• device – Default OpenVINO device ("AUTO"/"CPU"/"GPU"/"NPU"). Can be overridden per call.

• precision – Target IR precision for conversion (defaults to the manifest value, or fp16).

• **kwargs (Any) – Passed to the pipeline when model names a capability (for example Model("face_analyze", attributes=("age_gender",))).

• source (Any)

• **kwargs

반환 형식:

Any

classmethod network(model, task=None, device='AUTO', precision=None)

Load one network, even when the name also names a capability.

Model("gaze") gives you the composed pipeline, which is what a caller wants — but the pipeline itself needs the raw gaze network, and so does anyone who wants to drive it by hand. This skips the capability dispatch in __new__() and always returns a plain model.

매개변수:

• model (str | Path)

• task (str | None)

• device (str)

• precision (str | None)

반환 형식:

Model

property inputs: list[tuple[str, tuple[int, ...], str]]

Return (name, shape, dtype) for each model input.

Useful for non-image models (NLP / audio / time series): build matching tensors and pass them to infer().

infer(inputs, *, device=None)

Run the model on raw input tensor(s), returning {name: ndarray}.

The escape hatch for any model — including non-image ones (NLP / audio / time series) — where you provide the input tensors yourself (see inputs for the expected shapes). No image preprocessing is done.

매개변수:

• inputs (Any)

• device (str | None)

반환 형식:

dict[str, ndarray]

predict(source, *, device=None, imgsz=None, conf=0.25, stream=False, **kwargs)

Run prediction on source.

The input type is auto-detected. An image (path / ndarray / folder / video / camera int) runs the vision pipeline. An audio file on a sound model is read, resampled, framed and decoded into Results like any other task. Anything else (a .npy tensor, a raw non-image ndarray) is fed to the model directly and the raw {name: ndarray} outputs are returned. stream=True returns a generator for image sources.

매개변수:

• source (Any)

• device (str | None)

• imgsz (int | None)

• conf (float)

• stream (bool)

• kwargs (Any)

반환 형식:

list[Results] | Iterator[Results]

AUDIO_TASKS = frozenset({'noise_suppression', 'sound_classification'})

Tasks driven by audio rather than an image.

__call__(source, **kwargs)

Run on source, shaping the answer exactly as Model(name, source) does.

These two now mean the same thing:

Model("장면설명", "교실.jpg")           # ask once

m = Model("장면설명")                   # keep it, ask many times
m("교실.jpg")

Keeping the model around is the ordinary way to use it — a loop over a class’s photos, a lesson that runs the same capability twenty times — and it should not change the shape of the answer. One photo gives one Results, a folder gives a list, a webcam gives a stream, by the same rule both ways.

It used to be an alias for predict(), which always returns a list. That made m("교실.jpg")[0] necessary where Model(...) needed no index, and made m(0) try to collect a webcam into a list — a call that never returns.

predict() keeps the uniform shape, and passing stream= here goes straight to it: asking for a stream is asking for that form.

매개변수:

• source (Any)

• kwargs (Any)

반환 형식:

Any

quantize(calib_data, preset='int8', subset_size=300)

Post-training quantize the model with NNCF and cache the INT8 IR.

calib_data is an iterable of representative inputs (image paths or arrays). Requires the ovkit[quant] extra. After quantization the model serves predictions from the INT8 IR.

매개변수:

• calib_data (Sequence[Any])

• preset (str)

• subset_size (int)

반환 형식:

Path

class ovkit.Results(orig_img, task, names=None, *, boxes=None, masks=None, keypoints=None, probs=None, tensors=None, path=None)

기반 클래스: object

Container for a single image’s prediction.

매개변수:

• orig_img (np.ndarray)

• task (str)

• names (dict[int, str] | None)

• boxes (Boxes | None)

• masks (Masks | None)

• keypoints (Keypoints | None)

• probs (Probs | None)

• tensors (dict[str, np.ndarray] | None)

• path (str | None)

orig_img

The original HWC BGR image.

task

"detect" / "classify" / "segment" / "pose".

names

{id: class_name} mapping.

boxes, masks, keypoints, probs

Populated according to task; the others are None.

path

Source path, when the prediction came from a file.

tensors

Raw {output_name: ndarray} for tasks without a typed decoder (e.g. super-resolution, embeddings). None for vision tasks.

text: str | None

Decoded text for OCR/text-recognition tasks (otherwise None).

labels: list[str] | None

One label per box, when a pipeline knows something the class id does not (the word an OCR pipeline read, a face’s age and emotion). Takes the place of name conf in plot() and summary().

track_ids: list[int] | None

One track id per box, set by Tracker.

arrows: ndarray | None

(N, 4) arrows [x1, y1, x2, y2] to draw — a direction a number cannot show (where a face is looking, which way something moved).

audio: tuple[ndarray, int] | None

(samples, sample_rate) for audio results; orig_img then holds the waveform, so plot/save work exactly as they do for a picture.

display: ndarray | None

A picture this result wants shown instead of the input — a colourised depth map, a subject cut out of its background. Boxes and keypoints would mean nothing drawn on top of it, so plot() returns it with only the caption added.

elapsed_ms: float | None

How long inference took and where it ran (“CPU”/”GPU”/”NPU”). On an AI PC this pair is teaching material, so every result carries it.

property found: list[dict]

What was found, as friendly dictionaries.

Each row: {"name", "name_en", "score", "box", "pos"} — name in the display language ($OVKIT_LANG), name_en the stable English key (hyphenated, e.g. cell-phone) that code compares against, and pos a 9-grid position (“왼쪽 위”) for students who have not met coordinates yet. A classification result yields one row with no box.

label_for(i)

The label drawn for box i: a pipeline’s own, else name conf.

매개변수:

i (int)

반환 형식:

str

crop(i=None, pad=0.0)

Cut box i out of the image (all boxes when i is None).

pad grows the box by a fraction of its size — face attribute models want a little context around the detection.

매개변수:

• i (int | None)

• pad (float)

반환 형식:

ndarray | list[ndarray]

to_dict()

Plain-Python view of the result — ready for json.dumps or a DB.

반환 형식:

dict

to_json(**kwargs)

The result as a JSON string (**kwargs go to json.dumps).

반환 형식:

str

name_for(cls_id)

매개변수:

cls_id (int)

반환 형식:

str

summary(max_items=5)

One human-readable line describing this result.

Every surface (CLI, web demo, print(results)) renders through this, so a model’s answer reads the same everywhere — and reads as an answer (“cat 0.92”, “road 47% · car 8%”) rather than as tensor shapes.

매개변수:

max_items (int)

반환 형식:

str

plot(line_width=2, font_scale=None, caption=True)

Render this result onto a copy of the image and return it.

Draws masks, boxes (with name conf labels) and keypoints, then one caption — summary() — across the top. font_scale defaults to a size derived from the image width, so a 320-px webcam frame and a 4K photo are equally readable; pass caption=False to leave the top of the image clean.

매개변수:

• line_width (int)

• font_scale (float | None)

• caption (bool)

반환 형식:

ndarray

show(title='ovkit', wait=1)

Put the drawn result in a window. Returns False when asked to stop.

Every webcam example needs this, and every one of them wrote cv2.imshow — which raises on the OpenCV ovkit actually depends on. opencv-python-headless has no window support, so the demos in the README crashed for anyone who installed exactly what the README told them to, with a message about rebuilding OpenCV with GTK+.

Here it degrades instead: the first time a window cannot be opened it says so and how to fix it, and from then on the frames are written to files. wait=0 blocks until a key is pressed (a still), wait=1 keeps a stream moving.

매개변수:

• title (str)

• wait (int)

반환 형식:

bool

save(path)

Write the result to path.

An audio result saved to .wav writes the audio; anything else renders with plot() and writes an image. Saving the denoised signal is the point of running a denoiser, so it should not require digging the array out by hand.

매개변수:

path (str | Path)

반환 형식:

Path

class ovkit.Boxes(data)

기반 클래스: object

Detection boxes in xyxy pixel coordinates with scores and classes.

data is an (N, 6) array of [x1, y1, x2, y2, conf, cls].

매개변수:

data (np.ndarray)

property xyxy: ndarray

(N, 4) boxes as [x1, y1, x2, y2].

property conf: ndarray

(N,) confidence scores.

property cls: ndarray

(N,) integer class ids (as float; cast as needed).

property xywh: ndarray

(N, 4) boxes as [cx, cy, w, h].

class ovkit.Masks(data)

기반 클래스: object

Instance segmentation masks: (N, H, W) boolean/float array.

매개변수:

data (np.ndarray)

class ovkit.Keypoints(data)

기반 클래스: object

Pose keypoints: (N, K, 3) array of [x, y, confidence].

매개변수:

data (np.ndarray)

property xy: ndarray

property conf: ndarray

class ovkit.Probs(data)

기반 클래스: object

Classification probabilities over the class table.

매개변수:

data (np.ndarray)

property top1: int

Index of the highest-probability class.

property top5: ndarray

Indices of the five highest-probability classes (descending).

ovkit.list_models(tier='core')

Registered model names, sorted — the curated set by default.

tier=None returns everything, including the Open Model Zoo entries kept for compatibility. Those still load by name; they are simply not what a beginner should have to scroll past.

매개변수:

tier (str | None)

반환 형식:

list[str]

ovkit.list_pipelines()

Return {name: description} for every composed pipeline.

반환 형식:

dict[str, str]

Composed pipelines

Composed capabilities — several models chained into one intuitive call.

Model("face_detection") gives you boxes. What you usually want is who is in the frame, how old they look and whether they are smiling — which is a detector plus three more models plus the code to crop and join them. That is what a pipeline is:

from ovkit import Model

r = Model(“face_analyze”)(“group.jpg”) print(r.summary()) # 2 faces: age 31 · male 98% · happy 92%, … r.save(“faces.jpg”)

Every pipeline takes the same sources as Model (path, ndarray, folder, video, camera index) and returns the same Results, so they are drop-in replacements for a model anywhere in your code.

ovkit.list_pipelines() shows every capability and what it does.

ovkit.pipelines.build_pipeline(name, device='AUTO', **kwargs)

Build a composed pipeline by name — normally reached via Model(name).

>>> from ovkit import Model
>>> Model("face_analyze")("group.jpg").summary()
>>> Model("read_text")("sign.jpg").text
>>> Model("track")(0)                   # webcam, ids kept across frames

매개변수:

• name (str)

• device (str)

• kwargs (Any)

반환 형식:

Pipeline

ovkit.pipelines.capability_using(network)

Which capability drives this network, if one does.

A multi-input model like gaze_estimation_adas_0002 cannot be run from a picture — but a pipeline builds its inputs. Looking that up here lets the error say so instead of leaving the caller stuck.

매개변수:

network (str)

반환 형식:

str | None

ovkit.pipelines.is_pipeline(name)

True when name is a composed capability rather than one network.

매개변수:

name (str)

반환 형식:

bool

ovkit.pipelines.resolve_name(name)

Return the canonical pipeline name for name, or None.

매개변수:

name (str)

반환 형식:

str | None

ovkit.pipelines.list_pipelines()

Return {name: description} for every composed pipeline.

반환 형식:

dict[str, str]

ovkit.pipelines.PIPELINES: dict[str, type[Pipeline]] = {'anomaly': <class 'ovkit.pipelines.anomaly.AnomalyModel'>, 'anonymize': <class 'ovkit.pipelines.privacy.Anonymizer'>, 'attendance': <class 'ovkit.pipelines.classroom.Attendance'>, 'attention': <class 'ovkit.pipelines.attention.AttentionAnalyzer'>, 'count': <class 'ovkit.pipelines.classroom.Counter'>, 'drowsiness': <class 'ovkit.pipelines.temporal.DrowsinessMonitor'>, 'exercise': <class 'ovkit.pipelines.classroom.RepCounter'>, 'face_analyze': <class 'ovkit.pipelines.analyze.FaceAnalyzer'>, 'face_match': <class 'ovkit.pipelines.reid.ReID'>, 'gaze': <class 'ovkit.pipelines.gaze.GazeEstimator'>, 'gesture': <class 'ovkit.pipelines.temporal.GestureRecognizer'>, 'person_analyze': <class 'ovkit.pipelines.analyze.PersonAnalyzer'>, 'posture': <class 'ovkit.pipelines.classroom.PostureCoach'>, 'read_plate': <class 'ovkit.pipelines.plates.PlateReader'>, 'read_text': <class 'ovkit.pipelines.text.TextReader'>, 'scene': <class 'ovkit.pipelines.scene.SceneReport'>, 'speak': <class 'ovkit.pipelines.speak.Speaker'>, 'teach': <class 'ovkit.pipelines.teach.Teach'>, 'track': <class 'ovkit.pipelines.tracking.Tracker'>, 'vehicle_analyze': <class 'ovkit.pipelines.analyze.VehicleAnalyzer'>}

Every composed capability, by the name Model() accepts.

class ovkit.pipelines.Pipeline(device='AUTO')

기반 클래스: object

Several models composed into one capability.

Subclasses implement run() for a single image; source handling, model caching and lazy loading come from here.

매개변수:

device (str)

name: str = 'pipeline'

Name this pipeline is registered under (Model("face_analyze")).

description: str = ''

One-line description, shown by ovkit.list_pipelines().

task

Mirrors Model.task so a pipeline is a drop-in for a model.

model(name)

Return a sub-model, loading (and downloading) it on first use.

Always a single network: a pipeline’s parts are networks, and asking for one by a name that also names a capability (gaze names both) would otherwise hand back a pipeline — in the worst case this one. Loading is lazy, so a pipeline configured without, say, head pose never downloads that model.

매개변수:

name (str)

반환 형식:

Model

run(image, **kwargs)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• kwargs (Any)

반환 형식:

Results

predict(source, *, stream=False, **kwargs)

Run on any source Model accepts and return Results per image.

매개변수:

• source (Any)

• stream (bool)

• kwargs (Any)

반환 형식:

list[Results] | Iterator[Results]

class ovkit.pipelines.FaceAnalyzer(device='AUTO', attributes=None, detector=None)

기반 클래스: _DetectAndDescribe

Faces plus age, gender and emotion — the usual “who is in frame” answer.

>>> from ovkit import Model
>>> r = Model("face_analyze")("group.jpg")
>>> print(r.summary())     # 2 faces: age 31 · male 98% · happy 92%, ...
>>> r.save("faces.jpg")

attributes picks what to run; head_pose and face_landmarks are off by default because each is another model to download.

매개변수:

• device (str)

• attributes (tuple[str, ...] | list[str] | None)

• detector (str)

name: str = 'face_analyze'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Detect faces, then read age, gender and emotion from each.'

One-line description, shown by ovkit.list_pipelines().

detector: str = 'face_detection'

Registered name of the detector to find objects with.

available: tuple[str, ...] = ('age_gender', 'emotion', 'head_pose', 'face_landmarks')

Attribute models available, in the order their answers are joined.

default_attributes: tuple[str, ...] = ('age_gender', 'emotion')

Which of them run by default (the rest cost another download).

pad: float = 0.15

Grow each crop by this fraction — attribute models want some context.

noun: str = 'face'

What one detected object is called in the summary line.

run(image, *, conf=0.25, **kwargs)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• conf (float)

• kwargs (Any)

반환 형식:

Results

class ovkit.pipelines.PersonAnalyzer(device='AUTO', attributes=None, detector=None)

기반 클래스: _DetectAndDescribe

People plus what they are wearing or carrying.

>>> from ovkit import Model
>>> Model("person_analyze")("street.jpg").summary()
'3 persons: male 0.98 · long pants 0.95 · bag 0.71, ...'

매개변수:

• device (str)

• attributes (tuple[str, ...] | list[str] | None)

• detector (str)

name: str = 'person_analyze'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Detect people, then read their attributes (bag, hat, sleeves, ...).'

One-line description, shown by ovkit.list_pipelines().

detector: str = 'person_detection'

Registered name of the detector to find objects with.

available: tuple[str, ...] = ('person_attributes',)

Attribute models available, in the order their answers are joined.

default_attributes: tuple[str, ...] = ('person_attributes',)

Which of them run by default (the rest cost another download).

noun: str = 'person'

What one detected object is called in the summary line.

class ovkit.pipelines.VehicleAnalyzer(device='AUTO', attributes=None, detector=None)

기반 클래스: _DetectAndDescribe

Vehicles plus their type and colour.

>>> from ovkit import Model
>>> Model("vehicle_analyze")("parking.jpg").summary()
'2 vehicles: type: car (0.98) · color: black (0.83), ...'

매개변수:

• device (str)

• attributes (tuple[str, ...] | list[str] | None)

• detector (str)

name: str = 'vehicle_analyze'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Detect vehicles, then read type (car/bus/truck/van) and colour.'

One-line description, shown by ovkit.list_pipelines().

detector: str = 'vehicle_detection'

Registered name of the detector to find objects with.

available: tuple[str, ...] = ('vehicle_attributes',)

Attribute models available, in the order their answers are joined.

default_attributes: tuple[str, ...] = ('vehicle_attributes',)

Which of them run by default (the rest cost another download).

noun: str = 'vehicle'

What one detected object is called in the summary line.

class ovkit.pipelines.TextReader(device='AUTO', detector='text_detection', recognizer=None)

기반 클래스: Pipeline

Text detection + text recognition.

>>> from ovkit import Model
>>> r = Model("read_text")("receipt.jpg")
>>> r.text                     # every word, reading order (top to bottom)
>>> r.labels                   # the word on each box
>>> r.save("read.jpg")         # boxes labelled with what they say

매개변수:

• device (str)

• detector (str)

• recognizer (str | None)

name: str = 'read_text'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Find text regions and read them (detection + recognition).'

One-line description, shown by ovkit.list_pipelines().

recognizer

None means “match the display language” — Korean text needs the Korean recogniser, and asking for one explicitly is the override.

run(image, *, conf=0.25, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

class ovkit.pipelines.Tracker(device='AUTO', detector='detect', iou=0.3, max_age=30)

기반 클래스: Pipeline

A detector plus IoU association, emitting a track id per box.

매개변수:

• detector (str) – Registered detector name (any ovkit detector works).

• iou (float) – Minimum overlap for a detection to continue an existing track.

• max_age (int) – How many frames a track survives without a match before it is dropped, so a brief occlusion does not restart the id.

• device (str)

name: str = 'track'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Detect objects and keep a stable id for each across frames.'

One-line description, shown by ovkit.list_pipelines().

reset()

Forget every track (call between videos).

반환 형식:

None

run(image, *, conf=0.25, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

update(detections_xyxycc)

Assign a track id to each detection row and age out stale tracks.

Split out from run() so the association can be used (and tested) with detections from anywhere.

매개변수:

detections_xyxycc (ndarray)

반환 형식:

list[int]

class ovkit.pipelines.GazeEstimator(device='AUTO', detector='face_detection', eye_scale=0.55, gaze_model='gaze_estimation_adas_0002')

기반 클래스: Pipeline

Face detection + landmarks + head pose + gaze, in one call.

>>> from ovkit import Model
>>> r = Model("gaze")("portrait.jpg")
>>> r.summary()          # '1 face: looking left and slightly up'
>>> r.tensors["gaze"]    # (N, 3) unit vectors, one per face
>>> r.save("gaze.jpg")   # an arrow drawn from each eye

eye_scale sizes the eye crop as a fraction of the distance between the two eyes. The zoo demo sizes it from eye-corner landmarks, which the five-point landmark model does not provide; 0.55 is the equivalent width.

매개변수:

• device (str)

• detector (str)

• eye_scale (float)

• gaze_model (str)

name: str = 'gaze'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Estimate where a face is looking (detection + landmarks + head pose + gaze).'

One-line description, shown by ovkit.list_pipelines().

gaze_model

The gaze network. Spelled out because “gaze” now names this pipeline, and a pipeline cannot be its own part.

run(image, *, conf=0.25, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

class ovkit.pipelines.ReID(device='AUTO', embedder='face_reid', threshold=0.5)

기반 클래스: Pipeline

Embed crops and match them against a named gallery.

매개변수:

• embedder (str) – Registered embedding model: face_reid (faces), person_reid (whole people — the one that survives a face turning away), vehicle_reid_0001 (whole cars), or image_retrieval (scenes).

• threshold (float) – Below this similarity who() answers None instead of naming the closest gallery entry — without it every stranger gets somebody’s name.

• device (str)

name: str = 'face_match'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Match faces (or people, or vehicles) against a gallery you build.'

One-line description, shown by ovkit.list_pipelines().

embed(image)

Return the L2-normalised descriptor for one image or crop.

매개변수:

image (Any)

반환 형식:

ndarray

add(label, image)

Put an image in the gallery under label.

Adding the same label twice averages the descriptors, so several photos of one person give a more robust match than any single one.

매개변수:

• label (str)

• image (Any)

반환 형식:

ndarray

remove(label)

Drop a gallery entry.

매개변수:

label (str)

반환 형식:

None

match(image, top_k=1)

Return the top_k closest gallery labels as (label, score).

매개변수:

• image (Any)

• top_k (int)

반환 형식:

list[tuple[str, float]]

who(image)

The best match, or None when nothing clears threshold.

매개변수:

image (Any)

반환 형식:

tuple[str, float] | None

similarity(a, b)

Cosine similarity between two images, without touching the gallery.

매개변수:

• a (Any)

• b (Any)

반환 형식:

float

run(image, **_)

Matching needs a gallery, so who() is the entry point.

매개변수:

• image (ndarray)

• _ (Any)

class ovkit.pipelines.AttentionAnalyzer(device='AUTO', detector='detect', reach=2.0, steps=120)

기반 클래스: Pipeline

Gaze plus object detection: name the object on the line of sight.

>>> from ovkit import Model
>>> r = Model("attention")("desk.jpg")
>>> r.text            # '1 person looking at: laptop'
>>> r.arrows          # the ray drawn from each eye

매개변수:

• device (str)

• detector (str)

• reach (float)

• steps (int)

name: str = 'attention'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Work out which detected object a person is looking at (gaze + detection).'

One-line description, shown by ovkit.list_pipelines().

reach

How far to follow the ray, in multiples of the image diagonal.

run(image, *, conf=0.25, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

first_hit(origin, vector, boxes, shape)

Class id of the first box the gaze ray enters, or None.

Walking the ray in small steps (rather than solving per box) keeps the nearest object first without any depth information.

매개변수:

• origin (ndarray)

• vector (ndarray)

• boxes (Boxes)

• shape (tuple[int, int])

반환 형식:

int | None

class ovkit.pipelines.Anonymizer(device='AUTO', detector='face_detection', plates=False, method='pixelate', strength=1.0)

기반 클래스: Pipeline

Blur or pixelate every face (and optionally every number plate).

매개변수:

• plates (bool) – Also redact number plates. Costs one more model.

• method (str) – "pixelate" (visibly redacted) or "blur" (softer).

• strength (float) – Bigger is stronger: pixel block size and blur radius both scale with the region, so a small distant face is redacted as thoroughly as a close one.

• picture (The result's image is the redacted)

• and (so r.plot())

• kept (r.save() never hand back the original by accident. The regions are)

• covered. (in r.tensors["regions"] if you need to audit what was)

• device (str)

• detector (str)

name: str = 'anonymize'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Blur every face (and number plate) so a picture can be shared.'

One-line description, shown by ovkit.list_pipelines().

run(image, *, conf=0.25, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

class ovkit.pipelines.DrowsinessMonitor(device='AUTO', detector='face_detection', seconds=1.0, nod_pitch=20.0, eye_scale=0.55, clock=None)

기반 클래스: Pipeline

Driver monitoring: are the eyes closed, and for how long?

>>> from ovkit import Model
>>> monitor = Model("drowsiness")
>>> for r in monitor.predict(0, stream=True):     # webcam
...     print(r.summary())     # 'awake' ... 'EYES CLOSED 1.4s — drowsy'

Four models nobody can use alone: a face detector, the five-point landmark model for where the eyes are, open_closed_eye_0001 for their state, and head pose for a nodding head. The pipeline adds what none of them has — time: a blink is a fifth of a second, so only a closure lasting longer than seconds is drowsiness.

매개변수:

• device (str)

• detector (str)

• seconds (float)

• nod_pitch (float)

• eye_scale (float)

• clock (Callable[[], float] | None)

name: str = 'drowsiness'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Watch a face over time and warn when the eyes stay shut (driver monitoring).'

One-line description, shown by ovkit.list_pipelines().

reset()

Forget the closure currently being timed.

반환 형식:

None

run(image, *, conf=0.25, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

class ovkit.pipelines.GestureRecognizer(device='AUTO', model_name='common_sign_language_0002', classes='sign_language12')

기반 클래스: Pipeline

Hand gestures from a moving picture, not a still one.

>>> from ovkit import Model
>>> gestures = Model("gesture")
>>> for r in gestures.predict(0, stream=True):
...     print(r.summary())     # 'collecting frames (3/8)' ... 'thumb up 0.94'

common_sign_language_0002 takes a clip of eight frames. Fed a single image it is shown the same photograph eight times, which is not a gesture — so this keeps a rolling buffer of the last eight frames and classifies the motion across them.

매개변수:

• device (str)

• model_name (str)

• classes (str)

name: str = 'gesture'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Recognise hand gestures from the last few frames (needs motion, not a photo).'

One-line description, shown by ovkit.list_pipelines().

reset()

Drop the buffered frames (call between videos).

반환 형식:

None

run(image, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• _ (Any)

반환 형식:

Results

class ovkit.pipelines.PlateReader(device='AUTO', detector='license_plate', recognizer='text_recognition', attributes=True)

기반 클래스: Pipeline

Detect vehicles and plates, read the plates, describe the vehicles.

>>> from ovkit import Model
>>> r = Model("read_plate")("gate.jpg")
>>> r.text                    # 'black car — 12GA3456'
>>> r.to_dict()["boxes"]      # each box with its own text

매개변수:

• device (str)

• detector (str)

• recognizer (str)

• attributes (bool)

name: str = 'read_plate'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Read number plates and describe the vehicle each belongs to.'

One-line description, shown by ovkit.list_pipelines().

run(image, *, conf=0.25, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

class ovkit.pipelines.SceneReport(device='AUTO', detector='detect', segment=True, faces=True)

기반 클래스: Pipeline

Detection + segmentation + faces, summarised as one line.

Each part can be switched off: Model("scene", segment=False) skips the segmentation model (and its download) entirely.

매개변수:

• device (str)

• detector (str)

• segment (bool)

• faces (bool)

name: str = 'scene'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Describe a whole picture: objects, what the space is made of, and the people.'

One-line description, shown by ovkit.list_pipelines().

run(image, *, conf=0.25, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

class ovkit.pipelines.Teach(device='AUTO', mode='photo', k=5, load=None)

기반 클래스: Pipeline

Learn categories from examples; recognise them like any other model.

매개변수:

• device (str)

• mode (str)

• k (int)

• load (str | Path | None)

name: str = 'teach'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Teach your own AI from a few examples — no GPU training (5 modes).'

One-line description, shown by ovkit.list_pipelines().

learn(label, source)

Add examples of label: a folder, one image path, or an array.

Returns how many examples were stored. Call again with the same label to add more — more examples make a steadier answer.

매개변수:

• label (str)

• source (Any)

반환 형식:

int

forget(label)

Drop everything learned under label.

매개변수:

label (str)

반환 형식:

None

property labels: list[str]

The labels taught so far (in first-taught order).

guess(source)

The best label and its confidence for one image.

매개변수:

source (Any)

반환 형식:

tuple[str, float]

run(image, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• _ (Any)

반환 형식:

Results

score(source)

Grade the AI on a folder of subfolders (one per true label).

매개변수:

source (Any)

반환 형식:

Score

save(name, dir=None)

Write everything learned to <Documents>/ovkit/<name>.json.

매개변수:

• name (str)

• dir (str | Path | None)

반환 형식:

Path

배우기(label, source)

Add examples of label: a folder, one image path, or an array.

Returns how many examples were stored. Call again with the same label to add more — more examples make a steadier answer.

매개변수:

• label (str)

• source (Any)

반환 형식:

int

맞혀봐(source)

The best label and its confidence for one image.

매개변수:

source (Any)

반환 형식:

tuple[str, float]

점수(source)

Grade the AI on a folder of subfolders (one per true label).

매개변수:

source (Any)

반환 형식:

Score

저장(name, dir=None)

Write everything learned to <Documents>/ovkit/<name>.json.

매개변수:

• name (str)

• dir (str | Path | None)

반환 형식:

Path

잊어버려(label)

Drop everything learned under label.

매개변수:

label (str)

반환 형식:

None

class ovkit.pipelines.AnomalyModel(device='AUTO', model_path=None, metadata=None, threshold=None)

기반 클래스: Pipeline

anomalib’s OpenVINOInferencer, wrapped to return ovkit results.

매개변수:

• model_path (str | Path | None) – Path to the model.xml anomalib exported (PatchCore, EfficientAD, PaDiM, …).

• metadata (str | Path | None) – Optional metadata.json written next to the model; it carries the normalisation and threshold, without which scores are not comparable.

• threshold (float | None) – Score above which a part is called anomalous. None uses the threshold in the metadata.

• device (str)

name: str = 'anomaly'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Score a part as normal or anomalous with an anomalib model.'

One-line description, shown by ovkit.list_pipelines().

run(image, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• _ (Any)

반환 형식:

Results

class ovkit.pipelines.Attendance(device='AUTO', roster=None, threshold=0.5, detector='face_detection')

기반 클래스: Pipeline

Take the roll with face matching against a roster you provide.

>>> att = Model("attendance", roster="class_photos/")
>>> for r in att.predict(0, stream=True):
...     print(r)                      # 출석 3: 철수, 영희, 민수
>>> att.save_csv("roll.csv")          # name,status,score

The roster folder holds either one photo per student (철수.jpg) or a folder per student with several photos (better). Matching is the same cosine gallery as face_match, run on every detected face crop.

매개변수:

• device (str)

• roster (str | None)

• threshold (float)

• detector (str)

name: str = 'attendance'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Face-match against a roster folder and keep who is present.'

One-line description, shown by ovkit.list_pipelines().

load_roster(folder)

Fill the gallery from a roster folder; returns the names loaded.

매개변수:

folder (str)

반환 형식:

list[str]

property roster: list[str]

property absent: list[str]

reset()

반환 형식:

None

run(image, *, conf=0.25, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

save_csv(path)

Write name,status,score for the whole roster.

매개변수:

path (str)

반환 형식:

str

class ovkit.pipelines.Counter(device='AUTO', detector='detect', what=None)

기반 클래스: Pipeline

Count what a detector sees, optionally only one kind of thing.

>>> Model("count", "desk.jpg").summary()        # 'pencil 3 · cup 1'
>>> Model("count", 0, what="person")            # live head-count

매개변수:

• device (str)

• detector (str)

• what (str | None)

name: str = 'count'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Count the objects in view, by kind (optionally just one kind).'

One-line description, shown by ovkit.list_pipelines().

what

English class key to count exclusively (person, cell-phone …).

run(image, *, conf=0.25, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

class ovkit.pipelines.PostureCoach(device='AUTO', degrees=25.0, seconds=5.0, clock=None)

기반 클래스: Pipeline

Warn when the neck stays bent past a threshold — the turtle-neck timer.

>>> for r in Model("posture", 0):
...     print(r)          # '자세 좋아요 (12°)' ... '목이 34° — 자세 고치세요'

A single glance down is not bad posture, so the warning needs the angle to stay past degrees for seconds — the same time-not-frames logic as drowsiness. Works best with the camera at screen height, face-on or side-on.

매개변수:

• device (str)

• degrees (float)

• seconds (float)

• clock (Callable[[], float] | None)

name: str = 'posture'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Watch the neck angle over time and warn when posture slips.'

One-line description, shown by ovkit.list_pipelines().

reset()

반환 형식:

None

run(image, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• _ (Any)

반환 형식:

Results

class ovkit.pipelines.RepCounter(device='AUTO', kind='squat')

기반 클래스: Pipeline

Count exercise repetitions from the pose stream.

>>> for r in Model("exercise", 0, kind="squat"):
...     print(r)          # 'squat x 12 (down)'

A rep is one full cycle through hysteresis: the joint angle must drop below the exercise’s down threshold and come back above up — so a half-hearted bounce in the middle never counts.

매개변수:

• device (str)

• kind (str)

name: str = 'exercise'

Name this pipeline is registered under (Model("face_analyze")).

description: str = 'Count squats / push-ups by tracking joint angles over time.'

One-line description, shown by ovkit.list_pipelines().

reset()

반환 형식:

None

run(image, **_)

Analyse one image. Implemented by each pipeline.

매개변수:

• image (ndarray)

• _ (Any)

반환 형식:

Results

update(person)

Feed one pose; returns the rep count (exposed for testing).

매개변수:

person (ndarray)

반환 형식:

int

Exceptions

Exception hierarchy for ovkit.

All errors raised by ovkit derive from OVKitError so callers can catch the whole family with a single except.

exception ovkit.core.errors.OVKitError

기반 클래스: Exception

Base class for every error raised by ovkit.

exception ovkit.core.errors.ModelNotFoundError

기반 클래스: OVKitError

A model name could not be resolved to a local path or manifest entry.

exception ovkit.core.errors.OfflineError

기반 클래스: OVKitError

Network access was required but OVKIT_OFFLINE=1 is set.

exception ovkit.core.errors.DownloadError

기반 클래스: OVKitError

A model artifact failed to download or failed its integrity check.

exception ovkit.core.errors.GatedModelError

기반 클래스: DownloadError

A Hugging Face repo is gated and requires authentication.

exception ovkit.core.errors.MirrorMissingError

기반 클래스: DownloadError

A model is expected on the ovkit HF mirror but is not (yet) there.

exception ovkit.core.errors.ConversionError

기반 클래스: OVKitError

Conversion of a source model (ONNX/torch) to OpenVINO IR failed.

exception ovkit.core.errors.TaskDetectionError

기반 클래스: OVKitError

The task (detect/classify/segment/pose) could not be determined.

exception ovkit.core.errors.LicenseError

기반 클래스: OVKitError

A model carries a non-permissive license and may not be registered.

ovkit.core.errors.multi_input_message(model_name, input_names)

The message for a model fed one image when it needs several inputs.

Written once because it was drifting into three near-identical copies, and because the useful half — naming the capability that builds those inputs — only existed in one of them.

매개변수:

• model_name (str)

• input_names (list[str])

반환 형식:

str

Core modules

Model registry: load the manifest and resolve a name to a source spec.

The registry is intentionally data-driven. Models live in YAML manifests (src/ovkit/manifests/*.yaml plus any user-supplied paths), never hardcoded in Python. Adding a model is a one-line YAML edit.

class ovkit.core.registry.ModelEntry(name, src, task=None, description=None, license=None, precision='fp16', repo=None, filename=None, subfolder=None, url=None, sha256=None, imgsz=None, license_url=None, tier='core', fallback=None, preprocess=<factory>, postprocess=<factory>, extra=<factory>)

기반 클래스: object

A single resolved manifest entry.

Attributes mirror the YAML schema documented in manifests/models.yaml.

매개변수:

• name (str)

• src (str)

• task (str | None)

• description (str | None)

• license (str | None)

• precision (str)

• repo (str | None)

• filename (str | None)

• subfolder (str | None)

• url (str | None)

• sha256 (str | None)

• imgsz (int | None)

• license_url (str | None)

• tier (str)

• fallback (dict[str, Any] | None)

• preprocess (dict[str, Any])

• postprocess (dict[str, Any])

• extra (dict[str, Any])

name: str

src: str

task: str | None = None

description: str | None = None

license: str | None = None

precision: str = 'fp16'

repo: str | None = None

filename: str | None = None

subfolder: str | None = None

url: str | None = None

sha256: str | None = None

imgsz: int | None = None

license_url: str | None = None

tier: str = 'core'

"core" for the curated set ovkit puts in front of you, "zoo" for the rest of the Open Model Zoo — still loadable by name, just not in the way of someone deciding what to try first.

"part" is neither: a network that is a piece of a capability and does nothing alone. Supertonic’s vocoder turns a latent into a waveform, which is not a thing anyone has lying around. “zoo” would have been the lazy answer and would have been wrong in a way that matters — zoo means “superseded, still here”, and a capability built on superseded models is exactly what test_no_capability_is_built_on_an_archived_model exists to catch. Hiding parts under the same word would have blunted that check.

fallback: dict[str, Any] | None = None

preprocess: dict[str, Any]

postprocess: dict[str, Any]

extra: dict[str, Any]

classmethod from_dict(name, data)

매개변수:

• name (str)

• data (dict[str, Any])

반환 형식:

ModelEntry

exception ovkit.core.registry.OVKitManifestError

기반 클래스: Exception

Raised when a manifest file cannot be parsed.

ovkit.core.registry.reload()

Clear the cached manifest (call after editing manifests at runtime).

반환 형식:

None

ovkit.core.registry.list_models(tier='core')

Registered model names, sorted — the curated set by default.

tier=None returns everything, including the Open Model Zoo entries kept for compatibility. Those still load by name; they are simply not what a beginner should have to scroll past.

매개변수:

tier (str | None)

반환 형식:

list[str]

ovkit.core.registry.tier_of(name, _seen=None)

"core", "zoo" or "part" for a name ("core" if unknown).

An alias inherits its target’s tier: hiding a model but leaving its friendly name on the front page would only move the dead end.

매개변수:

• name (str)

• _seen (set[str] | None)

반환 형식:

str

ovkit.core.registry.resolve(name, _seen=None)

Resolve a registered model name to a ModelEntry.

Returns None if the name is not in any manifest. An alias entry ({alias: other_name}) transparently resolves to its target, so friendly capability names (e.g. face_detection -> face_detection_0205) work. The entry’s license is validated to be permissive; non-permissive entries raise LicenseError so they can never load.

매개변수:

• name (str)

• _seen (set[str] | None)

반환 형식:

ModelEntry | None

Artifact download + cache with atomic writes, integrity checks, offline mode.

This module turns a ModelEntry into a concrete local file (an .onnx or .xml) ready for conversion/loading. It does not know about OpenVINO; it only fetches bytes and verifies them.

Robustness guarantees (spec §6.5):

1. Atomic save — download to a temp file, rename into place on success.

2. Integrity — verify sha256 from the manifest when present.

3. Offline — OVKIT_OFFLINE=1 blocks the network; cache-only.

ovkit.core.download.OVKIT_MIRROR = 'leeyunjai/ovkit-models'

HF mirror that hosts OMZ-derived (Apache-2.0) IR for ovkit.

ovkit.core.download.model_cache_dir(name)

Return (and create) the cache directory for a model name.

매개변수:

name (str)

반환 형식:

Path

ovkit.core.download.downloads_dir(name)

Return (and create) the directory holding raw downloaded sources.

매개변수:

name (str)

반환 형식:

Path

ovkit.core.download.fetch(entry)

Ensure the source artifact for entry is present locally and return it.

Resolution order:

1. Offline (OVKIT_OFFLINE=1): return a cached copy or raise.

2. The entry’s primary source.

3. entry.fallback (e.g. the upstream original) if the primary fails — so a mirror outage degrades to the original host instead of breaking.

매개변수:

entry (ModelEntry)

반환 형식:

Path

ovkit.core.download.data_dir(group)

Return (and create) the cache directory for a group of data files.

매개변수:

group (str)

반환 형식:

Path

ovkit.core.download.fetch_data(repo, filename, *, group)

Download one auxiliary data file from the Hub and return its local path.

Some models are not just weights. A text-to-speech model needs the table that turns characters into ids and the vectors that give it a voice; a graph without them produces nothing. fetch() is about a model’s source artifact and only knows how to find one — this is the same cache, the same offline rule, for the files that travel beside it.

group keeps one model’s data together under the cache root, so removing a model removes its tables too.

매개변수:

• repo (str)

• filename (str)

• group (str)

반환 형식:

Path

Convert source models (ONNX / IR) to OpenVINO IR, with a conversion cache.

Conversion runs at most once per (name, precision): the resulting IR is written to the model cache and reused on subsequent loads.

ovkit.core.convert.cached_ir(name, precision)

Return the cached IR .xml for (name, precision) if it exists.

매개변수:

• name (str)

• precision (str)

반환 형식:

Path | None

ovkit.core.convert.to_ir(source, name, precision='fp16')

Convert source to OpenVINO IR and return the cached .xml path.

source may already be IR (.xml) — in that case it is passed through unchanged. ONNX sources are converted with openvino.convert_model and serialized (compressing weights to fp16 when precision == "fp16"). The result is cached so conversion happens only once.

매개변수:

• source (Path)

• name (str)

• precision (str)

반환 형식:

Path

Thin OpenVINO runtime wrapper: device abstraction, sync + async inference.

A Backend owns a compiled model for a chosen device and exposes both a single-shot infer() (synchronous) and a throughput-oriented infer_batch() built on ov.AsyncInferQueue for streams/folders/video.

ovkit.core.backend.core()

Return the shared openvino.Core, creating it on first use.

반환 형식:

Any

ovkit.core.backend.available_devices()

Return device names visible to OpenVINO (e.g. ["CPU", "GPU", "NPU"]).

반환 형식:

list[str]

class ovkit.core.backend.Backend(model, device='AUTO')

기반 클래스: object

A compiled model bound to a device, with sync and async inference.

매개변수:

• model (str | Path | Any) – Path to an IR .xml / ONNX file, or an already-built ov.Model.

• device (str) – OpenVINO device string. "AUTO" (default) lets OpenVINO pick.

property input_shape: tuple[int, ...]

Partial shape of the first input as a tuple (-1 for dynamic).

property actual_device: str

The device inference actually runs on (AUTO resolves to a real one).

output_signatures()

Return (name, shape) for each output (-1 for dynamic dims).

반환 형식:

list[tuple[str, tuple[int, …]]]

rt_info(*keys)

Read a runtime-info value from the underlying model, or None.

매개변수:

keys (str)

반환 형식:

str | None

infer(inputs)

Run one synchronous inference and return {output_name: ndarray}.

매개변수:

inputs (ndarray | dict[Any, ndarray])

반환 형식:

dict[str, ndarray]

infer_batch(feeds, callback=None, jobs=0)

Run inference over feeds using an async queue (throughput mode).

Yields result dicts in completion order. When callback is given it is invoked as callback(index, result); otherwise results are collected and yielded. jobs sets the number of in-flight requests (0 lets OpenVINO choose the optimal number).

매개변수:

• feeds (Iterable[ndarray | dict[Any, ndarray]])

• callback (Callable[[int, dict[str, ndarray]], None] | None)

• jobs (int)

반환 형식:

Iterator[dict[str, ndarray]]

Task auto-detection.

Priority (spec §4):

1. The manifest task field, if the model came from the registry.

2. The IR rt_info metadata (model_info/task or model_type).

3. A heuristic over the output tensor signatures.

4. Otherwise raise TaskDetectionError asking for an explicit task=.

ovkit.core.tasks.KNOWN_TASKS = ('detect', 'classify', 'segment', 'pose', 'face')

Tasks ovkit knows how to attach an adapter for.

ovkit.core.tasks.detect_task(backend, manifest_task=None, override=None)

Determine the task for a loaded model following the documented priority.

매개변수:

• backend (Backend) – A compiled Backend to introspect.

• manifest_task (str | None) – task from the registry entry, if any (highest non-override priority).

• override (str | None) – An explicit task= from the caller, which short-circuits everything.

반환 형식:

str

Recognition adapters

Task adapters: map a generic backend + image to task-specific Results.

The get_adapter() factory selects the adapter for a detected task. detect (DETR / SSD / boxes+labels / YOLOv2), classify, segment, and pose have typed decoders; every other image task falls back to GenericAdapter, which returns the raw output tensors.

class ovkit.recognize.BackgroundAdapter(*, imgsz=640, preprocess=None, postprocess=None, names=None)

기반 클래스: BaseAdapter

Salient-object segmentation: keep the subject, drop everything else.

매개변수:

• imgsz (int)

• preprocess (dict[str, Any] | None)

• postprocess (dict[str, Any] | None)

• names (dict[int, str] | None)

task: str = 'background'

run(backend, image, *, conf=0.5, **_)

Run the full pre/infer/post pipeline for a single image.

매개변수:

• backend (Backend)

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

class ovkit.recognize.BaseAdapter(*, imgsz=640, preprocess=None, postprocess=None, names=None)

기반 클래스: object

Common configuration + interface for every task adapter.

매개변수:

• imgsz (int)

• preprocess (dict[str, Any] | None)

• postprocess (dict[str, Any] | None)

• names (dict[int, str] | None)

task: str = 'base'

run(backend, image, **kwargs)

Run the full pre/infer/post pipeline for a single image.

매개변수:

• backend (Backend)

• image (ndarray)

• kwargs (Any)

반환 형식:

Results

preprocess_square(image, rgb=True)

Resize to imgsz square, normalize, and return an NCHW float tensor.

매개변수:

• image (ndarray)

• rgb (bool)

반환 형식:

ndarray

static labels_beside(model_path)

Class names from a labels.txt next to the model, if present.

Keeping labels as data (one name per line, mirrored with the model) avoids hardcoding a thousand ImageNet strings in the package and works for any dataset a model was trained on.

매개변수:

model_path (str | None)

반환 형식:

dict[int, str] | None

model_input_hw(backend)

Return the model’s static spatial (h, w) (last two dims), or imgsz.

Works for 4-D [N,C,H,W] and higher-rank inputs (e.g. video clips [N,C,T,H,W]); only the trailing two dims are taken as H, W. Raises a clear error for multi-input models, which a single image cannot drive automatically.

매개변수:

backend (Backend)

반환 형식:

tuple[int, int]

preprocess(image, size, rgb=True, scale=None)

Resize to (h, w), normalize, and return an NCHW float tensor.

scale overrides the manifest/default divisor (e.g. 1.0 to keep raw [0, 255] input, 255.0 to map to [0, 1]).

매개변수:

• image (ndarray)

• size (tuple[int, int])

• rgb (bool)

• scale (float | None)

반환 형식:

ndarray

class ovkit.recognize.ClassifyAdapter(*, imgsz=640, preprocess=None, postprocess=None, names=None)

기반 클래스: BaseAdapter

Adapter for image classification.

매개변수:

• imgsz (int)

• preprocess (dict[str, Any] | None)

• postprocess (dict[str, Any] | None)

• names (dict[int, str] | None)

task: str = 'classify'

run(backend, image, **_)

Run the full pre/infer/post pipeline for a single image.

매개변수:

• backend (Backend)

• image (ndarray)

• _ (Any)

반환 형식:

Results

class ovkit.recognize.DepthAdapter(*, imgsz=640, preprocess=None, postprocess=None, names=None)

기반 클래스: BaseAdapter

Monocular depth: a colourised map, plus where the nearest thing is.

매개변수:

• imgsz (int)

• preprocess (dict[str, Any] | None)

• postprocess (dict[str, Any] | None)

• names (dict[int, str] | None)

task: str = 'depth'

run(backend, image, **_)

Run the full pre/infer/post pipeline for a single image.

매개변수:

• backend (Backend)

• image (ndarray)

• _ (Any)

반환 형식:

Results

class ovkit.recognize.DetectAdapter(**kwargs)

기반 클래스: BaseAdapter

Adapter for object detection (DETR and SSD output families).

매개변수:

kwargs (Any)

task: str = 'detect'

run(backend, image, *, conf=0.25, max_det=300, **_)

Run the full pre/infer/post pipeline for a single image.

매개변수:

• backend (Backend)

• image (ndarray)

• conf (float)

• max_det (int)

• _ (Any)

반환 형식:

Results

class ovkit.recognize.FaceAdapter(*, imgsz=640, preprocess=None, postprocess=None, names=None)

기반 클래스: BaseAdapter

Adapter for face-analysis models (detection, attributes, landmarks).

매개변수:

• imgsz (int)

• preprocess (dict[str, Any] | None)

• postprocess (dict[str, Any] | None)

• names (dict[int, str] | None)

task: str = 'face'

run(backend, image, conf=0.25, **_)

Run the full pre/infer/post pipeline for a single image.

매개변수:

• backend (Backend)

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

class ovkit.recognize.GenericAdapter(task='generic', **kwargs)

기반 클래스: BaseAdapter

Run an image through a model and return raw output tensors.

매개변수:

• task (str)

• kwargs (Any)

task: str = 'generic'

run(backend, image, **_)

Run the full pre/infer/post pipeline for a single image.

매개변수:

• backend (Backend)

• image (ndarray)

• _ (Any)

반환 형식:

Results

class ovkit.recognize.OCRAdapter(*, imgsz=640, preprocess=None, postprocess=None, names=None)

기반 클래스: BaseAdapter

Adapter for text recognition (greedy CTC).

매개변수:

• imgsz (int)

• preprocess (dict[str, Any] | None)

• postprocess (dict[str, Any] | None)

• names (dict[int, str] | None)

task: str = 'optical_character_recognition'

run(backend, image, **_)

Run the full pre/infer/post pipeline for a single image.

매개변수:

• backend (Backend)

• image (ndarray)

• _ (Any)

반환 형식:

Results

class ovkit.recognize.PoseAdapter(*, imgsz=640, preprocess=None, postprocess=None, names=None)

기반 클래스: BaseAdapter

Adapter for keypoint/pose estimation (multi-instance heatmap peaks).

매개변수:

• imgsz (int)

• preprocess (dict[str, Any] | None)

• postprocess (dict[str, Any] | None)

• names (dict[int, str] | None)

task: str = 'pose'

run(backend, image, *, conf=0.1, **_)

Run the full pre/infer/post pipeline for a single image.

매개변수:

• backend (Backend)

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

class ovkit.recognize.SegmentAdapter(*, imgsz=640, preprocess=None, postprocess=None, names=None)

기반 클래스: BaseAdapter

Adapter for semantic and instance segmentation.

매개변수:

• imgsz (int)

• preprocess (dict[str, Any] | None)

• postprocess (dict[str, Any] | None)

• names (dict[int, str] | None)

task: str = 'segment'

property class_table: dict[int, str]

Class names for this model — a mask of “class_15” says nothing.

run(backend, image, *, conf=0.25, **_)

Run the full pre/infer/post pipeline for a single image.

매개변수:

• backend (Backend)

• image (ndarray)

• conf (float)

• _ (Any)

반환 형식:

Results

ovkit.recognize.VISION_TASKS = frozenset({'background', 'classify', 'depth', 'detect', 'face', 'ocr', 'optical_character_recognition', 'pose', 'segment'})

Tasks with a typed decoder (the rest use the generic raw-output adapter).

ovkit.recognize.get_adapter(task, **kwargs)

Instantiate the adapter for task.

Vision tasks (detect/classify/segment/pose) get their typed decoder; any other task falls back to GenericAdapter, which runs the model on the image and returns raw output tensors.

매개변수:

• task (str)

• kwargs (Any)

반환 형식:

BaseAdapter

Detection adapter — DETR-family and SSD/DetectionOutput models.

Two output families are auto-detected from the model’s output signature:

• DETR (RT-DETR / D-FINE): a class-logits tensor [N, Q, C] and a box tensor [N, Q, 4] in normalized cxcywh form. No NMS — each query is one prediction. Sigmoid the logits, take the best class per query, threshold.

• SSD / DetectionOutput (most OMZ detectors: face/person/vehicle): a single [1, 1, N, 7] tensor of [image_id, label, conf, x_min, y_min, x_max, y_max] with normalized coordinates. Threshold by conf.

Preprocessing follows the model’s own input size (OMZ models are fixed-size) and sensible per-family defaults (DETR: RGB [0,1]; SSD: raw BGR [0,255]), both overridable via the manifest preprocess block.

class ovkit.recognize.detect.DetectAdapter(**kwargs)

기반 클래스: BaseAdapter

Adapter for object detection (DETR and SSD output families).

매개변수:

kwargs (Any)

task: str = 'detect'

run(backend, image, *, conf=0.25, max_det=300, **_)

Run the full pre/infer/post pipeline for a single image.

매개변수:

• backend (Backend)

• image (ndarray)

• conf (float)

• max_det (int)

• _ (Any)

반환 형식:

Results

Image utilities

Image utilities — not models. Resize, letterbox, color, crop, zoom.

Everything here works on plain numpy HWC arrays (OpenCV’s BGR convention by default) so the rest of ovkit never has to depend on a particular image type.

ovkit.image.ops.imread(path)

Read an image file into an HWC BGR uint8 array.

Reads the bytes with Python and decodes them with OpenCV, rather than handing OpenCV the path. cv2.imread passes the name to the C++ runtime, which on Windows uses the system code page — so 철수.png arrived as 泥좎닔.png and the read failed. A roster folder full of Korean names is exactly what Model("출석체크") is for, so the path never reaches OpenCV.

매개변수:

path (str | Path)

반환 형식:

ndarray

ovkit.image.ops.imwrite(path, img)

Write an HWC BGR array to path.

Encoded by OpenCV, written by Python — the same reason as imread().

매개변수:

• path (str | Path)

• img (ndarray)

반환 형식:

None

ovkit.image.ops.bgr_to_rgb(img)

Swap the channel order between BGR and RGB (works both ways).

매개변수:

img (ndarray)

반환 형식:

ndarray

ovkit.image.ops.resize(img, size)

Resize to size (a square edge length or (w, h)).

매개변수:

• img (ndarray)

• size (int | tuple[int, int])

반환 형식:

ndarray

ovkit.image.ops.letterbox(img, size=640, color=(114, 114, 114))

Resize preserving aspect ratio and pad to size.

Returns (padded_image, scale, (pad_x, pad_y)) so detections can be mapped back to the original image coordinates.

매개변수:

• img (ndarray)

• size (int | tuple[int, int])

• color (tuple[int, int, int])

반환 형식:

tuple[ndarray, float, tuple[int, int]]

ovkit.image.ops.crop(img, box)

Crop an xyxy box (floats are clamped to image bounds).

매개변수:

• img (ndarray)

• box (tuple[float, float, float, float])

반환 형식:

ndarray

ovkit.image.ops.zoom(img, factor)

Scale an image by factor (>1 enlarges, <1 shrinks).

매개변수:

• img (ndarray)

• factor (float)

반환 형식:

ndarray