Typy Results

Obiekt Results

Jeden Results opisuje jeden obraz. Pojedyncze źródło obrazu zwraca jeden taki obiekt, źródło będące listą lub katalogiem zwraca listę, a stream=True zwraca generator, który je emituje.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt")result = model(SAMPLE_IMAGE) print(result.orig_shape, result.path)print(result.boxes.xyxy)print(result.boxes.conf)print(result.names[int(result.boxes.cls[0])])

Pola danych

Każde pole ma wartość None, jeśli model go nie utworzył. Rodzina wypełnia pole zależne od swojego zadania.

result.normals jest aliasem do odczytu i zapisu dla result.normal_map.

Jednocześnie może być ustawione więcej niż jedno pole. Model segmentacji wypełnia zarówno boxes, jak i masks; model gaze wypełnia boxes ramkami twarzy i gaze kątami; model siatki wypełnia boxes ramkami osób oraz meshes wyrównanymi do nich według wierszy.

Boxes

Ramki detekcji dla jednego obrazu.

with_id(id) i with_orig_shape(orig_shape) zwracają nowy obiekt Boxes z zastąpionym odpowiednim polem.

Masks

Maski instancji dla jednego obrazu. data jest tensorem maski, xy zwraca kontury poszczególnych instancji w pikselach, a xyn zwraca je znormalizowane.

Keypoints

Punkty kluczowe pozy wyrównane wierszami z boxes. xy jest parą współrzędnych każdego punktu kluczowego, a xyn parą znormalizowaną. conf jest trzecim kanałem, gdy dane go zawierają, w przeciwnym razie ma wartość None. has_visible jest tablicą logiczną, której wartość jest true tam, gdzie conf > 0, a gdy nie ma kanału pewności, wszystkie wartości są true.

Points

Lokalizacja punktów dla jednego obrazu. data ma kształt (N, 4) z wierszami x, y, class, confidence. Współrzędne są bezwzględnymi pikselami; xy, cls i conf rozdzielają kolumny, a xyn normalizuje współrzędne.

Probs

Wyniki klasyfikacji. top1 jest zwycięskim indeksem, top5 pięcioma najlepszymi indeksami, a top1conf i top5conf ich wynikami.

OBB

Obrócone ramki. data zawiera 7 lub 8 wartości w każdym wierszu: xywhr, opcjonalny identyfikator śledzenia, a następnie pewność i klasę.

Gaze

Kąty spojrzenia dla poszczególnych twarzy w radianach, o kształcie (N, 2), wyrównane wierszami z ramkami twarzy w boxes. Kolumna 0 to nachylenie pitch, a kolumna 1 to odchylenie yaw, zgodnie z konwencją L2CS: dodatnie yaw obraca spojrzenie w lewo osoby, a dodatnie pitch obraca je w dół. pitch_deg i yaw_deg konwertują wartości na stopnie, a direction_3d zwraca jednostkowy wektor kierunku.

SemanticMask

Gęsta mapa semantyczna o kształcie (H, W) z całkowitymi identyfikatorami klas na pierwotnym obszarze obrazu. 255 jest wartością ignorowaną i nigdy nie jest liczone jako klasa (SemanticMask.IGNORE_INDEX). classes wymienia obecne identyfikatory klas, a class_mask(class_id) zwraca maskę logiczną jednej klasy.

PanopticSegmentation

Każdy piksel otrzymuje dokładnie jeden nienakładający się segment, co łączy regiony stuff i instancje thing. data jest całkowitoliczbową mapą identyfikatorów segmentów (H, W). Identyfikator segmentu 0 oznacza brak etykiety (PanopticSegmentation.IGNORE_INDEX). segments_info jest listą słowników, po jednym na segment, a każdy zawiera co najmniej {"id": int, "category_id": int}, gdzie id odpowiada wartości w mapie, a category_id indeksuje names. segment_ids wymienia obecne identyfikatory, a segment_mask(segment_id) zwraca maskę logiczną jednego segmentu.

Podział thing i stuff jest właściwością kategorii, a nie segmentu. Dane mogą zdenormalizować tę informację na każdy segment jako "isthing": bool. Jeśli to robią, wartość musi być zgodna z mapą na poziomie kategorii.

DepthMap

Gęsta mapa względnej odwrotności głębi, o kształcie zmiennoprzecinkowym (H, W) na pierwotnym obszarze obrazu. Wyższe wartości oznaczają położenie bliżej kamery. Wartości są względne, a nie metryczne w metrach. min, max i mean są obliczane dla wartości skończonych, a normalized() skaluje mapę do [0, 1].

DepthMap(data, orig_shape=None, encoding="inverse_depth") przyjmuje też encoding="depth" i encoding="log_depth". Walidatory interpretują to przed dopasowaniem. Wartości względnej głębi nadal nie gwarantują skali metrycznej.

NormalMap

Gęste pole normalnych powierzchni, float32 (H, W, 3) na pierwotnym obszarze obrazu, w układzie kamery OpenCV: +x w prawo, +y w dół, +z w głąb sceny. Normalne są skierowane do kamery, więc powierzchnia równoległa do płaszczyzny obrazu ma wartość (0, 0, -1). Każdy piksel jest wektorem jednostkowym. assert_normalized(atol=1e-4) sprawdza ten niezmiennik.

EdgeMap

Gęsta mapa prawdopodobieństwa krawędzi, float32 (H, W) na pierwotnym obszarze obrazu, gdzie 0 oznacza brak krawędzi, a 1 oznacza krawędź. Zachowywana jest mapa ciągła, aby wybór progu należał do kodu wywołującego: binary(threshold=0.5) stosuje próg, a array zwraca widok numpy.

RestoredImage

Przywrócony obraz RGB, (H, W, 3) uint8. Dla super-rozdzielczości obszar jest Results.restore_scale razy większy od wejścia. array zwraca widok numpy, a save(path) zapisuje obraz.

Matte

Miękki matte krycia, float32 (H, W) w zakresie [0, 1] na pierwotnym obszarze obrazu. 1 oznacza w pełni pierwszy plan, a 0 w pełni tło. Miękki matte obejmuje twardą maskę usuwania tła progowaną przy 0.5 i zachowuje wygładzone krawędzie, które odrzuca maska binarna. array zwraca widok numpy.

Dla wyniku matte Results.cutout(image=None) zwraca tablicę RGBA uint8 (H, W, 4), której czwarty kanał jest matte, a Results.save(path, image=None) zapisuje ten wycięty obraz jako PNG z przezroczystym tłem. Obie metody pobierają RGB z image, jeśli je podano, a w przeciwnym razie wczytują je ponownie z Results.path.

OCRRegions

Zlokalizowany tekst wraz z transkrypcjami. data to wielokąty zmiennoprzecinkowe (N, 4, 2) w pikselach pierwotnego obrazu, uporządkowane jako lewy górny, prawy górny, prawy dolny i lewy dolny. Regiony występują w kolejności czytania, od góry do dołu, a następnie od lewej do prawej. texts jest listą N transkrypcji. conf jest wynikiem rozpoznawania dla każdego regionu, a det_conf wynikiem detekcji. Oba mają kształt (N,).

Czworokąty detekcji są rzeczywistymi wielokątami, więc nie wypełniają Results.boxes. xyxy zwraca ich obwiednie wyrównane do osi.

Embeddings

Wektory znormalizowane normą L2 z zadania embed, zawsze o kształcie (N, D). Wynik całego obrazu zawiera jeden wiersz i nie ma ramek, a embeddingi regionów są wyrównane wierszami z boxes. Ponieważ każdy wiersz jest znormalizowany, podobieństwo cosinusowe jest iloczynem skalarnym.

Identities

Nazwane dopasowania z galerii, wyrównane wierszami z embeddings. Są tworzone, gdy Gallery zostanie przekazane do predykcji embed. name jest listą, w której wpis ma wartość None poniżej progu dopasowania, a nazwa najbliższa, lecz niespełniająca progu, nigdy nie jest zgadywana. score jest tablicą wyników dopasowania, a data łączy ją z nazwami.

Meshes

Parametryczne siatki ludzkiego ciała, wyrównane wierszami z ramkami osób w boxes. Wszystko znajduje się w układzie kamery pierwotnego obrazu. transl jest wartością metryczną w metrach, gdzie +z wskazuje od kamery. vertices i joints3d są metryczne i zawierają już transl. joints2d jest wyrażone w pikselach pierwotnego obszaru obrazu, a nie wycięcia widzianego przez sieć. Żadne pole nie zawiera układu świata ani grawitacji.

Układy parametrów różnią się między modelami ciała, dlatego kształty nie są zakodowane na stałe. body_model nazywa parametryzację, a liczby są odczytywane z tensorów: num_vertices, num_joints, num_betas i has_vertices. params zwraca słownik parametrów, a save_obj(path, index=0) zapisuje jedną siatkę. Pola to global_orient, body_pose, betas, transl, vertices, faces, joints3d, joints2d, conf, focal_length i extras.

Dla body_model="mhr" obroty są kątami Eulera w radianach, a nie osią i kątem, body_pose jest płaskim wektorem parametrów poszczególnych stawów zamiast jednej trójki na staw, a betas są współczynnikami kształtu tożsamości. Skala szkieletu, poza dłoni i wyraz twarzy znajdują się w extras.

Konwersja i wybór

Każde pole danych ma metody to(*args, **kwargs), cpu(), cuda() i numpy(), a wywołanie jednej z nich na Results stosuje ją jednocześnie do każdego wypełnionego pola.

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt")result = model(SAMPLE_IMAGE) # Wszystkie dane są przenoszone razem.result = result.cpu().numpy() # Wiersze jako zwykłe słowniki, a następnie jako JSON.print(result.summary()[:1])print(result.to_json())

result[idx] wybiera wiersze ze wszystkich danych wyrównanych wierszami. len(result) jest liczbą detekcji albo liczbą punktów, gdy nie ma ramek. result.update(...) zwraca kopię z zastąpionymi nazwanymi polami. Przyjmuje każde pole oraz track_id i restore_scale.

summary i to_json

summary(normalize=False, decimals=5, embeddings=False) zwraca listę zwykłych słowników, po jednym wierszu na detekcję, segment, punkt lub region, zależnie od ustawionych pól. to_json(**kwargs) przekazuje argumenty do summary i zwraca ciąg JSON.

plot() renderuje dane każdego zadania. Nakładki na obrazy domyślnie zwracają tablice BGR; pil=True żąda PIL. Mapy głębi, normalnych, krawędzi i albedo, prostopadłościany 3D oraz fragmenty akcji domyślnie zwracają obraz PIL; pil=False zwraca tablicę.

Boxes3D

Boxes3D(data, orig_shape=None, intrinsics=None) przechowuje wiersze (N, 14): środek xyz, wymiary wlh, kwaternion wxyz, wynik rankingowy, identyfikator klasy, pewność 2D i pewność 3D. Współrzędne są wyrażone w metrach w układzie kamery: x w prawo, y w dół, z do przodu; nie zakłada się układu świata. Parametry wewnętrzne 3x3 odnoszą się do oryginalnego obszaru obrazu. Wiersze odpowiadają Results.boxes.

AlbedoMap

AlbedoMap(data, orig_shape=None) przechowuje liniowe RGB. Konwersja do wyświetlania tworzy sRGB; ilościowa walidacja albedo używa oryginalnych wartości liniowych.

Actions

Actions(data, orig_shape=None, names=None, fps=None, instruction=None) reprezentuje fragment akcji float32 (T, D). first zwraca pierwszy wiersz; wycinanie wybiera kroki czasowe. Wartości pozostają w jednostkach zbioru danych polityki. names opisuje wymiary akcji, fps częstotliwość sterowania, a instruction tekst warunkujący.

GeneratedImage

GeneratedImage(data, orig_shape=None, *, prompt=None, seed=None, params=None) przechowuje jeden zsyntetyzowany obraz, (H, W, 3) uint8 RGB. array zwraca widok numpy, a image obiekt PIL.Image. prompt to tekst, który wytworzył obraz, a seed to liczba całkowita, która odtwarza go przy tym samym modelu i ustawieniach; params zapisuje resztę wywołania: model, imgsz i każde ustawienie rodziny, które obowiązywało. save(path) zapisuje obraz, a PNG zapisuje też to_dict(), czyli kształt, prompt, seed i params, jako JSON w tekstowym fragmencie libreyolo.

W wygenerowanym wyniku Results.boxes i Results.path mają wartość None, orig_shape to własne (H, W) obrazu, a len(result) wynosi 1. Results.save(path) zapisuje obraz, plot() zwraca go jako obraz PIL, a summary() zwraca jeden wiersz z rekordem danych.

Gaussians

Gaussians(xyz, scales, rotations, opacities, sh, *, camera=None, seed=None, params=None, input_image=None) przechowuje jeden wygenerowany obiekt 3D jako gaussiany (splaty) we własnym układzie obiektu: z do góry, wyśrodkowany w sześcianie [-0.5, 0.5]^3. Każdy wiersz to jeden gaussian.

len(gaussians) to N, a gaussians[gaussians.opacities > 0.1] zwraca nowy obiekt Gaussians z wybranymi wierszami. save(path) zapisuje według rozszerzenia. .ply to standardowy układ 3D Gaussian Splatting, z logarytmicznymi skalami i logitowymi nieprzezroczystościami, obrócony y do góry, jak oczekują przeglądarki splatów, oraz z wierszem nagłówka comment libreyolo zawierającym seed, kamerę i params jako JSON. Dane z kolorem wyższego rzędu (K > 1) zgłaszają NotImplementedError dla .ply. .splat to zwarty format webowy, 32 bajty na gaussian. render(size=512, background=(0, 0, 0)) zwraca rzut punktowy z wywnioskowanego widoku wejściowego jako PIL.Image, szybki podgląd, a nie rasteryzację gaussianów.

W wygenerowanym wyniku 3D Results.boxes ma wartość None; path, orig_shape i orig_img opisują obraz źródłowy, a len(result) wynosi 1. Results.save(path) zapisuje obiekt, plot() zwraca ten rzut punktowy, a summary() zwraca jeden wiersz z rekordem danych.