CAM_ENCODER V01

Diagnostická read-only aplikace pro ověření, zda lze z obrazu kamery Basler odhadovat posun textury, rychlost pohybu a virtuální enkoderové impulzy.

English documentation

Stav V01: funkce akvizice a výpočtu byly ověřeny jednotkovými, syntetickými a omezenými hardwarovými testy. Absolutní přesnost vůči kalibrovanému referenčnímu pohybu je NOT TESTED.

Účel projektu

CAM_ENCODER je testovací nástroj pro posouzení proveditelnosti kamerového měření rychlosti v situacích, kde se v obraze pohybuje dostatečně texturovaný povrch. Typickým experimentem je pohled kamery na pás, materiál nebo díl a porovnání kamerového odhadu s referenčním enkoderem nebo známou dráhou.

Aplikace:

• zachytává snímky z předem nastavené kamery Basler;
• v několika softwarových ROI vyhodnotí dvourozměrný posun mezi snímky;
• převede zvolenou složku posunu z pixelů na milimetry;
• sloučí výsledky robustním mediánem;
• vypočítá okamžitou rychlost, integrovanou dráhu a virtuální pulzy;
• zpřístupní diagnostiku kvality, BlockID, výpadků a doby výpočtu.

V01 není certifikovaný měřicí přístroj, bezpečnostní snímač, real-time řídicí prvek ani náhrada hardwarového enkoderu bez samostatné kalibrace a validačního testu.

Hlavní funkcionalita

Oblast	Chování V01
Kamera	Přesný runtime výběr zařízení, read-only načtení parametrů a akvizice Mono8
Časová báze	Rozdíl BlockID dělený naposledy načteným resulting FPS
Detekce pohybu	Fázová korelace OpenCV pro každou aktivní softwarovou ROI
Výchozí ROI	Pět navazujících oblastí přes celou šířku, výška 50 % obrazu
Fúze	Medián platných posunů; výchozí minimum 3 platné ROI z 5
Kvalita	Minimální korelace, minimální textura a mrtvé pásmo posunu
Výstupy	Rychlost, filtrovaná rychlost pro GUI, dráha, frekvence a počet pulzů
Obsluha	Ruční kreslení/editace ROI, reset, export/import konfigurace a obnovení readbacku
Testování	Syntetický zdroj, jednotkové testy a omezený hardwarový smoke test

Read-only bezpečnostní kontrakt

Aplikace nezapisuje žádné GenICam parametry kamery. ROI kamery, offset, binning, pixel format, expozice, gain a frame rate se pouze načtou a zobrazí. Kamerová vrstva používá jen:

• enumeraci a přesný runtime výběr zařízení;
• otevření a zavření kamery;
• čtení dostupných uzlů;
• StartGrabbing a StopGrabbing.

Neprovádí User Set, Force IP, změny síťového nastavení, firmware, GPIO ani jiné perzistentní operace. Nastavení kamery je nutné provést mimo aplikaci, například v pylon Vieweru, se zastavenou akvizicí CAM_ENCODER.

Sériové číslo slouží pouze interně k jednoznačnému runtime výběru. Neukládá se do konfiguračních souborů, reportů ani logů.

Výpočet posunu a rychlosti

1. Posun v ROI

Pro každou aktivní ROI se z předchozího a aktuálního snímku vypočítá posun dx_px, dy_px pomocí cv2.phaseCorrelate. Podle vybrané osy se použije horizontální nebo vertikální složka.

2. Čas mezi zpracovanými snímky

frame_gap = current_BlockID - previous_BlockID
dt        = frame_gap / loaded_resulting_fps

loaded_resulting_fps pochází z BslResultingAcquisitionFrameRate, případně z kompatibilního ResultingFrameRate. Hodnota se načte při startu a zůstane pro výpočet zmrazená až do ručního obnovení.

Chybějící, nulový nebo neklesající BlockID zneplatní dvojici snímků. Hardwarový timestamp a hostitelská přijímací frekvence jsou pouze diagnostické a nevstupují do rychlosti.

3. Převod pixelů na milimetry

V01 používá pinhole aproximaci:

effective_pitch_mm = pixel_pitch_um × camera_binning_axis / 1000
mm_per_pixel       = effective_pitch_mm × distance_mm / focal_length_mm
                     × scale_correction
displacement_mm    = selected_shift_px × mm_per_pixel
speed_mm_s         = displacement_mm / dt

Binning X a Y se načítá samostatně a použije se hodnota odpovídající měřené ose. Každá ROI může mít vlastní vzdálenost. scale_correction umožňuje pozdější korekci podle referenčního pohybu.

Tato geometrie předpokládá přibližně kolmý pohled, známou pracovní vzdálenost a dostatečně malou perspektivní chybu. Jedna kamera sama neurčuje hloubku.

4. Fúze a integrace

Z platných ROI se vytvoří medián posunů v milimetrech. Výchozí měření vyžaduje alespoň tři platné oblasti. Při 0–2 platných ROI:

• celková rychlost a pulzní frekvence jsou okamžitě nulové;
• integrovaná dráha se nezmění;
• GUI zobrazí důvod, například platné ROI 2/3.

Dráha se integruje z nefiltrovaného mediánového posunu. Vyhlazená rychlost je pouze informativní údaj v GUI a nemění virtuální pulzy.

Pět ROI přes celý horizontální rozsah

Tlačítko Vytvořit 5 ROI přes šířku vytvoří pět oblastí bez mezer a překryvů. Hranice jsou:

x[i] = floor(i × image_width / 5)

Výška je 50 % obrazu a ROI jsou svisle vystředěné. Pro obraz 960×250 vznikne pět oblastí 192×125 s Y=62. Pokud šířka není dělitelná pěti, rozdíl šířek oblastí je nejvýše jeden pixel a celý horizontální rozsah zůstane pokrytý.

Existující ROI se nahrazují až po potvrzení. Ruční kreslení, úprava, deaktivace a mazání zůstávají dostupné.

Prahy kvality

Minimální korelace Q

Q je diagnostická odezva fázové korelace. Vyšší hodnota obvykle znamená jednoznačnější shodu mezi snímky. Není to pravděpodobnost ani univerzálně kalibrované procento. Výchozí práh je 0,08.

• Příliš nízký práh může přijímat šum nebo nejednoznačné posuny.
• Příliš vysoký práh může odmítat použitelné snímky při rozmazání, změně osvětlení nebo slabší textuře.

Minimální textura σ

Textura je směrodatná odchylka jasů uvnitř ROI. Výchozí minimum je 3,0 úrovně šedi.

• Jednolitá nebo přesvětlená plocha má nízkou texturu a neposkytuje spolehlivý obrazový vzor.
• Vysoká textura sama o sobě nezaručuje správný posun; stále musí projít korelace.

Mrtvé pásmo

Výchozí mrtvé pásmo 0,5 px potlačuje malé posuny způsobené šumem a subpixelovou nestabilitou. Posun pod prahem se považuje za nulový. Vyšší hodnota zlepší klidový stav, ale sníží citlivost k pomalému pohybu.

Prahy je nutné ověřovat na skutečné scéně, rychlosti, expozici a optice.

Virtuální enkoder

Uživatel nastaví počet pulzů na milimetr:

pulse_frequency_hz = abs(speed_mm_s) × pulses_per_mm
signed_pulses      = integrated_distance_mm × pulses_per_mm

Výstup je pouze softwarová hodnota. V01 negeneruje elektrické impulzy a Windows GUI neposkytuje deterministický hardwarový trigger.

Požadavky a instalace

• Windows x64;
• Python 3.11 x64;
• Basler pylon Software Suite a pypylon 26.6;
• OpenCV, NumPy a PySide6;
• předem nakonfigurovaná kamera pro hardwarový režim.

Automatická příprava prostředí:

.\setup_env.ps1

Spuštění včetně testů:

run_windows.bat

Automatický start vybrané kamery:

.\run_windows.bat --auto-start

Ruční spuštění:

.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe self_test.py
.\.venv\Scripts\python.exe camera_encoder_app.py

Doporučený testovací postup

1. Nejdříve zvolte syntetický zdroj a ověřte pět ROI, nenulovou rychlost a integraci dráhy.
2. Zastavte pylon Viewer a jiné procesy, které mohou vlastnit kameru.
3. Spusťte Basler zdroj a zkontrolujte read-only panel.
4. Vytvořte pět ROI a ve statické scéně ověřte nulovou rychlost i frekvenci.
5. Pohybujte texturovaným objektem v obou směrech a ověřte znaménko.
6. Sledujte počet platných ROI, korelaci, texturu, výpadky a dobu výpočtu.
7. Externě změněné dynamické hodnoty převezměte tlačítkem Znovu načíst hodnoty z kamery.
8. Pro vyhodnocení přesnosti porovnejte výsledek s referenčním enkoderem nebo známou dráhou a rychlostí.

Při změně rozměrů, binningu nebo pixel formátu během obnovení se měření zastaví a nevyhovující ROI se zneplatní.

Read-only hardwarový smoke test

Test vyžaduje přesný model a Device User ID zadané pouze za běhu:

.\.venv\Scripts\python.exe hardware_smoke_test.py `
  --model "<MODEL_NAME>" `
  --user-id "<DEVICE_USER_ID>" `
  --frames 200

Lokální report ověřuje kladné resulting FPS, rozměr a formát, posloupnost BlockID, počet zachycených snímků a nezměněná strukturální nastavení. Identifikátory jsou redigovány a reports/ je ignorováno Gitem.

Konfigurace v2

Vzor je v examples/config_v2.example.json. Konfigurace ukládá pouze optiku, osu, prahy kvality, softwarová ROI a parametry virtuálního enkoderu. Neukládá hardwarové ROI, binning, FPS, sériové číslo, Device User ID ani IP adresu. Staré hardwarové hodnoty z konfigurace v1 se při migraci ignorují.

Verze konfigurace 2 není totéž jako verze aplikace V01.

Interpretace a omezení výsledků

Výsledek mohou ovlivnit:

• pohybové rozmazání a příliš dlouhá expozice;
• periodická, proměnlivá nebo nedostatečná textura;
• změny osvětlení, stíny a odlesky;
• perspektiva, vibrace kamery a změna vzdálenosti;
• nesprávné ohnisko, rozteč pixelu, binning nebo kalibrační násobek;
• příliš velký posun mezi snímky nebo nedostatečný resulting FPS.

Ruční obousměrný test ověřuje směr a základní odezvu, nikoli metrologickou přesnost. Absolutní přesnost V01 zůstává NOT TESTED, dokud nebude provedena kalibrace a opakovatelný test proti referenci.

Licence a vztah k výrobci

Projekt je dostupný pod MIT licencí. Jde o nezávislý diagnostický projekt a není oficiálním produktem ani podporovaným nástrojem společnosti Basler.