Vision API Polski

Przegląd Rozwiązania

API Vision jest przeznaczone do zapewnienia kompleksowego rozwiązania dla zadań związanych z widzeniem komputerowym. Łączy ono przetwarzanie wstępne, inferencję, postprocessing i serwowanie w jednym żądaniu do endpointu. Wykorzystuje Triton jako źródło inferencji, w połączeniu z operacjami przetwarzania obrazu i wideo przyspieszonymi dzięki GPU . Do serwowania strumieni używa przyspieszonych przez GPU Serwerów Gstreamer.

Kluczowe funkcje:

• Plik obrazu jako wejście, detekcja, przetworzony plik obrazu jako wyjście
• Plik wideo jako wejście, detekcja, przetworzony plik wideo jako wyjście
• Strumień jako wejście, detekcja, przetworzony strumień RTSP jako wyjście

Jak uruchomić

Ponieważ Triton jest źródłem inferencji, najpierw musisz upewnić się, że jest on skonfigurowany i włączony Triton.

uwaga

Na ten moment Vision API akceptuje tylko standardowe wyjście modelu detekcji - [x1, x2, y1, y2, score, class_1, class_2 ..], jeżeli z jakiegoś powodu twój model ma inny output, API do nie przyjmie.

API Vision jest dostępne jako zasób obliczeniowy i wymaga różnych zasobów w zależności od wybranych operacji przetwarzania i rozdzielczości źródła. Aplikacja zawsze wymaga GPU, które obsługuje operacje przetwarzania obrazu. Najlepszym wyborem będzie A5000. Na początek zalecamy 1,5 rdzenia CPU i 1,5 GB RAM na każde wideo/strumień, który będziesz przetwarzać. Te wartości mogą wzrosnąć, gdy dodasz operacje lub użyjesz źródeł o wyższej rozdzielczości.

Aby uruchomić instancję, użyj następującej komendy:

cgc compute create --name vision-api -c 8 -m 12 -g 1 -gt A5000 vision-api

Po inicjalizacji możesz uzyskać dostęp do Swagger, aby zobaczyć wszystkie endpointy pod adresem:

https://vision-api.<namespace>.cgc-waw-01.comtegra.cloud/docs

Jak używać

Każdy endpoint będzie wymagał od Ciebie przekazania tokenu aplikacji jako źródła autoryzacji. Jest to ten sam token aplikacji, który możesz zobaczyć przy użyciu:

cgc compute list -d

Jak napisano w Kluczowych funkcjach, istnieją 3 sposoby korzystania z Vision API w zależności od pożądanego wejścia i wyjścia. Pierwsze 2, w których możesz uzyskać plik jako wyjście, będą miały podobny sposób użycia.

Najpierw prześlij plik na /image/upload lub /video/upload i otrzymasz uuid, który reprezentuje źródło. Następnie możesz go uwzględnić w żądaniu do image/to-image lub video/to-video. Zwróć uwagę na treść żądania:

{
  "source_file_uuid": "98ada9eb-daf6-4ee4-b4be-9fab7abdf619",
  "tritonServer": {
    "triton_url": "triton",
    "infer_model_name": "yolov8n",
    "version": "1"
  },
  "inference": {
    "confidence_threshold": 0.25,
    "iou_threshold": 0.45
  },
  "postprocess": {
    "bbox": {
      "apply": true,
      "rectangle_color": "default",
      "text_color": "default",
      "rectangle_thickness": 2,
      "text_size": 0.5,
      "text_thickness": 2,
      "include_text": false
    },
    "blur": {
      "apply": false,
      "blur_intensity": [99, 99]
    },
    "pose": {
      "apply": true,
      "keypoints": {
        "apply": true,
        "keypoint_color": [0, 165, 255],
        "line_color": [255, 165, 0],
        "radius": 5,
        "line_thickness": 2
      },
      "pose_classifier": {
        "apply": true,
        "slope_threshold": 40,
        "fall_detector": {
          "apply": false,
          "alert_threshold": 2
        }
      }
    }
  },
  "output_format": "jpg"
}

Tutaj możesz wpisać otrzymane uuid i zmienić wszystko, co chcesz w inferencji i postprocessingu. Po wypełnieniu treści żądania, wyślij je i poczekaj. Gdy przetwarzanie się zakończy, otrzymasz plik zawierający przetworzony obraz lub wideo.

Trzeci endpoint, który zwraca strumień RTSP, będzie wymagał podobnego żądania, ale natychmiast zwróci adres URL strumienia. Możesz go przechwycić, korzystając z tego adresu URL. Domyślnie strumień RTSP będzie dostępny tylko w Twojej przestrzeni nazw. Jeśli chcesz go zobaczyć na zewnętrznych maszynach, przejdź do sekcji Szczegółowe informacje.

Gdy nie potrzebujesz już strumienia, możesz go usunąć, przekazując stream_id do /stream/delete-stream.

Dostępny jest również endpoint informacyjny info/get-models, który pobiera modele dostępne na Triton z informacjami o nich.

Jeśli wolisz używać API nie przez Swagger, możesz wysyłać żądania w taki sposób:

curl -X 'POST' \
  'https://<appname>.<namespace>.cgc-waw-01.comtegra.cloud/video/to-stream' \
  -H 'accept: application/json' \
  -H 'app-token: 8d23ae613a4e46119f4d52cb25e8b551' \
  -H 'Content-Type: application/json' \
  -d '{
  "source_file_uuid": "ac839d89-14c7-4116-b5d8-30c34c714971",
  "tritonServer": {
    "triton_url": "triton",
    ...
  }

Wstawiając token aplikacji w nagłówku i parametry w body.

Szczegółowe informacje

Opcjonalne parametry aplikacji

Dodatkowe opcjonalne parametry, które możesz przekazać do polecenia create w CLI:

• MAX_STREAMS - maksymalna liczba strumieni, które mogą działać jednocześnie, domyślnie jest to liczba rdzeni CPU / 2.
• BUFFER_SIZE - rozmiar buforów sieciowych używanych przez aplikację. Najlepiej ustawić go na rozmiar nie większy niż Twoje MTU. Domyślnie 9000.
• GST_SERVERS - liczba serwerów Gstreamer. Domyślnie jest to MAX_STREAMS / 5. Jeśli Twoje źródło ma wyższą lub niższą rozdzielczość, możesz eksperymentować z tym parametrem, aby uzyskać optymalne zużycie zasobów.

Parametry żądania

Treść żądania ma kilka sekcji, zaczynając od sekcji Triton, gdzie musimy określić hosta Triton. W przypadku CGC, Triton postawiony w tym samym namespace będzie dostępny pod nazwą kontenera, na przykład: triton. Dodatkowo wybieramy model, którego chcemy użyć, jego wersję oraz triton_request_concurrency, który jest dostępny wyłącznie dla endpointu wideo i wskazuje, ile klientów będzie jednocześnie zapytaniać Triton. Jest to przykład parametru, który wpływa zarówno na czas wykonania zapytania, jak i zużycie zasobów, co należy wziąć pod uwagę.

Sekcja inferencji dotyczy typowych tematów dla inferencji modelu:

• confidence threshold
• intersection over union threshold

Sekcja postprocessingu dotyczy wszystkiego, co dzieje się po uzyskaniu wyników inferencji. Możemy wybrać nakładanie ramek w miejscach, gdzie model wykrył obiekty, rozmywanie tych obszarów lub użycie filtra Kalmana do poprawy ciągłości detekcji.

---

Konfiguracja Trackera

Oprócz opcji postprocessingu, takich jak nakładanie ramek, rozmazywanie obszarów lub używanie filtrów Kalmana, użytkownicy mogą modyfikować parametry trackera, aby zoptymalizować precyzję detekcji i poprawić funkcjonalność różnych funkcji, takich jak klasyfikacja pozycji, zliczanie obiektów oraz filtracja Kalmanem dla zapewnienia ciągłości detekcji. Eksperymentując z tymi parametrami, użytkownicy mogą dostosować swoje aplikacje, aby uzyskać lepszą dokładność i niezawodność.

Dostępne parametry do dostosowania:

Parametr	Domyślna wartość	Opis	Uwagi
track_activation_threshold	0.25	Próg pewności detekcji dla aktywacji śledzenia.	Zwiększenie tej wartości poprawia dokładność i stabilność, ale może pomijać prawidłowe detekcje. Zmniejszenie zwiększa kompletność, ale ryzykuje wprowadzenie szumu i niestabilności.
lost_track_buffer	30	Liczba klatek buforowanych po utracie śledzenia.	Zwiększenie tej wartości zmniejsza fragmentację śledzenia lub znikanie z powodu krótkich przerw w detekcji.
minimum_matching_threshold	0.8	Próg dopasowania śledzeń z detekcjami.	Zwiększenie tej wartości poprawia dokładność, ale ryzykuje fragmentacją. Zmniejszenie poprawia kompletność, ale zwiększa ryzyko fałszywych pozytywów.
frame_rate	"auto"	Liczba klatek na sekundę wideo. Jeśli ustawiona na "auto," liczba klatek na sekundę jest automatycznie wyodrębniana ze źródła.	Ustaw stałą liczbę klatek, jeśli liczba klatek na sekundę źródła jest zmienna lub nieznana.
minimum_consecutive_frames	1	Liczba kolejnych klatek, które obiekt musi być śledzony, zanim zostanie uznany za prawidłowy.	Zwiększenie tej wartości zapobiega tworzeniu przypadkowych śledzeń z fałszywej lub podwójnej detekcji, ale ryzykuje pomijanie krótszych śledzeń.

Część informacji o parametrach została pobrana z oficjalnej dokumentacji biblioteki Supervision.

---

Estymacja Pozy

Estymację pozy można skonfigurować przez ustawienie pose na true podczas używania modeli "Pose". Sekcja estymacji pozy zawiera następujący zestaw parametrów:

Parametr	Domyślna wartość	Opis	Uwagi
pose.apply	false	Włącza lub wyłącza funkcję estymacji pozycji.	Ustaw na true, aby aktywować estymację pozycji. Wymagane podczas korzystania z modeli "Pose Estimation".
keypoints.apply	true	Włącza lub wyłącza rysowanie punktów reprezentujących stawy ciała.	Punkty kluczowe reprezentują wykryte stawy.
keypoints.keypoint_color	[0, 165, 255]	Ustawia kolor BGR dla punktów kluczowych.	[0, 165, 255] dla żółtego.
keypoints.line_color	[255, 165, 0]	Ustawia kolor BGR dla linii łączących punkty kluczowe.	[255, 165, 0] dla niebieskiego.
keypoints.radius	5	Określa promień punktów kluczowych w pikselach.	Większe wartości zwiększają widoczność punktów kluczowych na klatce obrazu.
keypoints.line_thickness	2	Określa grubość linii łączących punkty kluczowe w pikselach.	Grubsze linie poprawiają widoczność przy wyższych rozdzielczościach klatek obrazu.
pose_classifier.apply	false	Włącza lub wyłącza klasyfikację pozycji.	Dostępne pozycje: Standing (stojąca) lub Laying (leżąca).
pose_classifier.slope_threshold	40	Ustawia kąt nachylenia do klasyfikacji pozycji jako leżącej.	Dostosuj wartość, aby precyzyjnie dostroić dokładność klasyfikacji pozycji.
fall_detector.apply	false	Włącza lub wyłącza funkcję wykrywania upadków.	Alerty wykrywania upadków mogą być przydatne w aplikacjach o krytycznym znaczeniu dla bezpieczeństwa.
fall_detector.alert_threshold	2	Określa próg czasowy (w sekundach) dla uruchomienia alertu upadku.	Niższe wartości zwiększają czułość wykrywania upadków; dostosuj w zależności od wymagań. Domyślnie alert o upadku zostanie wywołany, jeśli osoba leży przez dwie sekundy.

uwaga

Podczas korzystania z modeli do estymacji pozycji, należy ustawić parametr pose na true, aby zapewnić prawidłowe działanie.

Obecnie funkcja estymacji pozy obsługuje tylko modele YOLO-pose z 17 punktami kluczowymi w formacie COCO.

---

Liczenie Obiektów

Funkcja Liczenia Obiektów (object_counter) umożliwia zliczanie określonych klas obiektów, które poruszają się przez linię podziału w klatce wideo. Jest to szczególnie przydatne w scenariuszach takich jak monitorowanie ruchu drogowego, liczenie ludzi lub przedmiotów oraz analiza wzorców ruchu.

Poniższe parametry są dostępne do konfiguracji funkcji Liczenia Obiektów:

Parametr	Domyślna wartość	Opis	Uwagi
apply	true	Włącza lub wyłącza funkcję liczenia obiektów.	Ustaw true, aby aktywować funkcję liczenia obiektów.
line_type	"axis"	Określa typ linii używanej do liczenia obiektów. Wybierz "axis" dla linii poziomej/pionowej lub "custom" dla linii zdefiniowanej ręcznie.	Jeśli wybierzesz "axis", musisz określić oś (axis), na której linia będzie rysowana. Jeśli wybierzesz "custom", określ parametry line_start i line_end.
axis	"x"	Określa oś, na której rysowana jest linia dzieląca. Używane tylko, gdy line_type="axis".	Wybierz "x" dla linii pionowej lub "y" dla linii poziomej.
position	"1/2"	Określa pozycję linii dzielącej na wybranej osi. Używane tylko, gdy line_type="axis".	Akceptuje liczbę całkowitą (pozycję w pikselach) lub ułamek jako ciąg znaków (np. "1/2" dla środka klatki).
line_start	[null, null]	Definiuje punkt początkowy linii niestandardowej. Używane tylko, gdy line_type="custom".	Podaj współrzędne punktu początkowego linii w formacie [x, y]. Dowiedz się więcej...
line_end	[null, null]	Definiuje punkt końcowy linii niestandardowej. Używane tylko, gdy line_type="custom".	Podaj współrzędne punktu końcowego linii w formacie [x, y]. Dowiedz się więcej...
class_id_map	{"person": 0}	Mapuje nazwy klas obiektów na odpowiadające im identyfikatory klas.	Co najmniej jedna klasa musi zostać określona. Jeśli nie jesteś pewien identyfikatorów klas, skorzystaj z aplikacji Netron.
draw_counts	true	Wyświetla liczbę obiektów po obu stronach linii dzielącej.	Pokazuje, ile obiektów z każdej klasy przekroczyło linię w obu kierunkach.
draw_dividing_line	true	Rysuje linię dzielącą na klatce wideo.	Przydatne do wizualnego wskazania, gdzie obiekty są liczone.
line_color	[255, 255, 255]	Ustawia kolor linii dzielącej w formacie BGR.	[255, 255, 255] oznacza białą linię.
line_thickness	2	Określa grubość linii dzielącej.	Dostosuj w zależności od rozdzielczości klatki wideo, aby linia była bardziej widoczna.

informacja

Jak określić współrzędne dla parametrów line_start i line_end

Podczas definiowania punktu początkowego i końcowego linii niestandardowej należy podać współrzędne w formacie [x, y]. Współrzędne te reprezentują pozycje w siatce klatki wideo lub obrazu. Przykład działania:

1. Lewy górny róg: Lewy górny róg klatki to punkt (0, 0).
2. Oś pozioma (X): Współrzędna x zwiększa się w miarę przesuwania się w prawo wzdłuż klatki, co odpowiada szerokości klatki.
3. Oś pionowa (Y): Współrzędna y zwiększa się w miarę przesuwania się w dół klatki, co odpowiada wysokości klatki.

Na przykład:

• line_start: Określa punkt początkowy linii. Na przykład [0, 1080] umieści początek w lewym dolnym rogu klatki o rozdzielczości 1920x1080.
• line_end: Określa punkt końcowy linii. Na przykład [1920, 0] umieści koniec w prawym górnym rogu klatki o rozdzielczości 1920x1080.

---

Każda opcja ma swoje podopcje, które modyfikują ich zachowanie. Ponownie, ważne jest, aby pamiętać, że im więcej postprocessingu dodamy, tym dłużej potrwa zapytanie i tym więcej zasobów zostanie zużytych. Wszystkie opcje poza ramkami są domyślnie wyłączone. W przypadku kolorów domyślna opcja - "default" oznacza, że każda wykryta klasa będzie miała przypisany inny losowy kolor. Jeśli chcesz użyć określonego koloru, możesz podać go w formie tablicy RGB - np.: [255, 0, 0], wtedy KAŻDA klasa będzie miała ten kolor. Może to być przydatne, gdy masz tylko jedną lub kilka klas.

Na koniec mamy format wyjścia. Obecnie zaimplementowany jest tylko jeden format, więc domyślne ustawienie nie powinno być zmieniane.

Strumienie RTSP

RTSP używa TCP do transportu, ale CGC nie zapewnia opcji otwarcia portu TCP z poziomu CLI. Jeśli chcesz zobaczyć strumień na zewnętrznych maszynach, będziesz musiał ręcznie dodać porty TCP.

uwaga

Every Gstreamer server uses separate TCP port. First one serves on 9001 and every another on the next one, so 9002, 9003, ... . You will need to add TCP port for every one of them. Każdy z serwerów Gstreamera używa oddzielnego portu. 1 serwuje strumienie na porcie 9001, a reszta na kolejnych - 9002. 9003 .... Będziesz musiał otworzyć port TCP dla każdego z nich.

Błędy i rozwiązywanie problemów

Ta sekcja zawiera informacje o tym, gdzie zwracane są błędy podczas przetwarzania i jak je interpretować. Zrozumienie komunikatów o błędach i ich przyczyn pozwoli szybko rozwiązać problemy i zapewnić płynne działanie systemu.

Lokalizacja błędów

Większość błędów będzie widoczna w Responses > Server Response. Szczegółowe informacje o błędach można znaleźć w części Response Body odpowiedzi serwera.

Na przykład błąd dotyczący nieistniejącego pliku wideo (który może wystąpić, gdy parametr source_file_uuid jest nieprawidłowy) będzie wyglądał następująco:

---

Błędy w parametrach

W przypadku problemów z dostarczonymi parametrami w odpowiedzi znajdą się szczegółowe komunikaty o tym, co poszło nie tak. Poniżej znajduje się przykład takiego błędu:

{
  "detail": [
    {
      "type": "value_error",
      "loc": [
        "body",
        "postprocess",
        "pose",
        "pose_classifier",
        "slope_threshold"
      ],
      "msg": "Value error, Slope threshold must be between 0 and 90 degrees",
      "input": 150,
      "ctx": {
        "error": {}
      },
      "url": "https://errors.pydantic.dev/2.10/v/value_error"
    }
  ]
}

W tym przykładzie:

• Opis błędu: Parametr slope_threshold został podany z nieprawidłową wartością (150).
• Przyczyna: Prawidłowy zakres wartości dla slope_threshold to od 0 do 90 stopni.
• Rozwiązanie: Zaktualizuj wartość slope_threshold, aby mieściła się w dopuszczalnym zakresie.

Odpowiedź z błędem zawiera:

• Typ: Wskazuje typ błędu, np. value_error.
• Lokalizacja (loc): Pokazuje, gdzie w hierarchii parametrów wystąpił błąd.
• Wiadomość (msg): Zawiera dokładny opis błędu.
• Wprowadzone dane (input): Wyświetla podaną nieprawidłową wartość.
• URL: Link do dokumentacji z dodatkowymi szczegółami dotyczącymi typu błędu.

---

Błąd modelu do estymacji pozycji

Jeśli pojawi się następujący błąd:

RuntimeError encountered during pose estimation: shape '[1, 17, 3]' is invalid for input of size 0. Are you sure you are using a pose estimation model?

Oznacza to, że funkcja estymacji pozycji została włączona, ale używany model nie obsługuje estymacji pozycji.

Rozwiązanie:

1. Zmień model na taki, który obsługuje estymację pozycji (zobacz jak skonfigurować).
2. Alternatywnie wyłącz funkcję pose, ustawiając parametr apply na false w sekcji parametrów dotyczącej pozycji.

informacja

Punkt końcowy stream/to-stream zawsze zwraca adres URL dla strumienia wyjściowego. Jeśli zwrócony adres URL nie działa, logi można sprawdzić za pomocą następującego polecenia:

cgc logs <vision-api-compute-resource-name>

Na przykład dla powyższej konfiguracji polecenie wyglądałoby następująco:

cgc logs vision-api

To polecenie zapewni szczegółowe logi zasobów obliczeniowych Vision API, pomagając w diagnozowaniu i rozwiązywaniu problemów związanych ze strumieniem wyjściowym.

warning

Ze względu na wieloprocesową naturę endpointu /stream błędy mogą pojawić się w CGC z opóźnieniem.