Praktyczna Kalibracja w OpenCV5
Jak skalibrować kamerę telefonu przy pomocy OpenCV 5? W tym praktycznym tutorialu pokazuję cały proces na przykładzie iPhone’a 11 i mojego projektu Spatial Maintenance Copilot.

Table of contents
W poprzednim artykule wyjaśniłem, czym jest dystorsja obiektywu i dlaczego nawet kilka pikseli błędu może mieć znaczenie w Physical AI.
Teraz czas przejść do praktyki. Pokażę, jak skalibrowałem kamerę iPhone’a 11 przy pomocy OpenCV 5 i planszy ChArUco.
Nie będzie to jednak przykład oderwany od rzeczywistości. Wykorzystamy podejście z mojego projektu Spatial Maintenance Copilot, który stworzyłem na OpenCV AI Competition 2026.
W moim demonstratorze telefon patrzy na zamkniętą szafkę, za której klapą znajduje się ukryte pudełko. Zadaniem systemu jest wskazanie położenia tego pudełka na obrazie, mimo że kamera go nie widzi.
Żeby prawidłowo wyświetlić taką nakładkę, muszę znać parametry kamery. I właśnie je dzisiaj wyznaczymy.
Cały tutorial wykonamy w Pythonie i Google Colab.
1. Plansza do kalibracji ChArUco
W Spatial Maintenance Copilot wykorzystuję plansze ChArUco do dwóch różnych zadań.
Pierwsza służy do kalibracji kamery, czyli wyznaczenia ogniskowej, punktu głównego i dystorsji. Druga wyznacza układ współrzędnych szafki podczas budowania Component Atlas.
Dzisiaj zajmiemy się pierwszą.
| Parametr | Wartość |
|---|---|
| Układ | 5 x 7 kwadratów |
| Bok kwadratu | 30 mm |
| Bok markera | 21,6 mm |
| Słownik | DICT_5X5_100 |
| ID markerów | 0-16 |
| Rozmiar planszy | 150 x 210 mm |
Możemy wygenerować jej model w Pythonie:
import cv2 as cv
import numpy as np
import matplotlib.pyplot as plt
dictionary = cv.aruco.getPredefinedDictionary(
cv.aruco.DICT_5X5_100
)
board = cv.aruco.CharucoBoard(
(5, 7),
30.0,
21.6,
dictionary,
np.arange(17, dtype=np.int32)
)
image = board.generateImage((750, 1050))
plt.imshow(image, cmap="gray")
plt.axis("off")
plt.show()Do wydrukowania przygotowałem również PDF A4. Drukujemy go w rzeczywistym rozmiarze, bez dopasowania do strony.
To ważne, ponieważ OpenCV zakłada, że podane w kodzie wymiary odpowiadają rzeczywistej planszy.
Po wydrukowaniu sprawdzamy skalę linijką i mocujemy planszę na płaskiej powierzchni.
2. Nagrywamy materiał do kalibracji
W moim projekcie korzystałem z:
- iPhone’a 11,
- obiektywu 1×,
- rozdzielczości 1080 × 1920 px,
- pionowej orientacji obrazu.
Z materiału wideo wybrałem 58 klatek, które posłużyły do końcowej kalibracji.
Dlaczego aż tyle?
Algorytm musi zobaczyć, jak ta sama plansza wygląda z różnych perspektyw. Jeżeli wszystkie zdjęcia wykonamy idealnie na wprost, nie dostarczymy mu wystarczająco zróżnicowanych informacji.
Dlatego podczas nagrywania zmieniamy pozycję i nachylenie planszy, pokazując ją przy środku, krawędziach oraz w rogach kadru. Zmieniamy również odległość.
Unikamy przy tym rozmycia, odblasków i zmiany obiektywu.
Nie ma jednej magicznej liczby klatek. Ważniejsza jest ich jakość i różnorodność.
3. Uruchamiamy Google Colab
Zaczynamy od instalacji OpenCV w wersji używanej w mojej aplikacji:
%pip install -q --upgrade opencv-python-headless==5.0.0.93
Weryfikujemy środowisko:
import cv2 as cv
import numpy as np
import matplotlib.pyplot as plt
print(cv.__version__)Teraz możemy wgrać nagranie z telefonu:
from google.colab import files
uploaded = files.upload()Następnie pobieramy z niego klatki, które zostaną wykorzystane do kalibracji:
Następnie pobieramy z niego klatki, które zostaną wykorzystane do kalibracji:
from pathlib import Path
video_path = Path(next(iter(uploaded.keys())))
cap = cv.VideoCapture(str(video_path))
frames = []
index = 0
while True:
ok, frame = cap.read()
if not ok:
break
if index % 30 == 0:
frames.append(frame.copy())
index += 1
cap.release()
print("Liczba klatek:", len(frames))Wybieramy co trzydziestą klatkę, żeby nie analizować wielu prawie identycznych ujęć. Ten odstęp możemy zmienić zależnie od długości nagrania i prędkości ruchu.
4. Wykrywamy narożniki ChArUco
4. Wykrywamy narożniki ChArUco
Teraz OpenCV musi rozpoznać planszę na każdej klatce.
Tworzymy detektor:
detector = cv.aruco.CharucoDetector(board)Następnie zbieramy współrzędne narożników.
Dla każdego narożnika znamy jego położenie na planszy w milimetrach. Detektor dostarcza nam natomiast jego położenie na zdjęciu w pikselach.
object_points = []
image_points = []
for frame in frames:
gray = cv.cvtColor(
frame, cv.COLOR_BGR2GRAY
)
corners, ids, _, _ = detector.detectBoard(gray)
if ids is None or len(ids) < 4:
continue
obj, img = board.matchImagePoints(corners, ids)
board_xy = obj.reshape(-1, 3)[:, :2]
if np.linalg.matrix_rank(
board_xy - board_xy.mean(axis=0)
) < 2:
continue
object_points.append(obj)
image_points.append(img)
print("Poprawne ujęcia:", len(object_points))To właśnie odpowiedniki tych dwóch zbiorów danych przekazuję później do funkcji kalibracyjnej w Spatial Maintenance Copilot.
Warto też wyświetlić obraz z wykrytymi narożnikami:
preview = frame.copy()
cv.aruco.drawDetectedCornersCharuco(
preview, corners, ids
)
plt.imshow(cv.cvtColor(preview, cv.COLOR_BGR2RGB))
plt.axis("off")
plt.show()Dzięki takiej wizualizacji możemy łatwo sprawdzić, czy algorytm poprawnie zidentyfikował punkty.
5. Kalibrujemy kamerę przy pomocy OpenCV 5
Mamy już pary punktów. Teraz możemy wyznaczyć parametry kamery.
W mojej aplikacji wykorzystałem cv.calibrateCameraExtended, a nie tylko podstawową funkcję calibrateCamera.
Dlaczego?
Ponieważ oprócz macierzy kamery i współczynników dystorsji otrzymuję również odchylenia standardowe parametrów oraz błędy reprojekcji poszczególnych ujęć.
image_size = (frames[0].shape[1], frames[0].shape[0])
(
rms,
K,
dist,
rvecs,
tvecs,
std_intrinsics,
std_extrinsics,
per_view_errors
) = cv.calibrateCameraExtended(
object_points,
image_points,
image_size,
None,
None
)
print("RMS:", rms)
print("K:", K)
print("Distortion:", dist)W mojej rzeczywistej kalibracji otrzymałem:
Macierz kamery:
[
K =
\begin{bmatrix}
1674.710 & 0 & 531.599\
0 & 1677.423 & 956.229\
0 & 0 & 1
\end{bmatrix}
]
Współczynniki dystorsji:
Współczynniki dystorsji:
[
0.142101, # k1
-0.153974, # k2
0.000161, # p1
-0.003913, # p2
-0.212896 # k3
]<text>Rzeczywisty wynik kalibracji:</text> RMS = 0,900 px dla 58 klatek.
Wynik znajduje się w repozytorium w pliku calib/intrinsics/iphone11-1x-1080p-portrait.yml.
6. Sprawdzamy, czy kalibracja jest poprawna
Nie wystarczy otrzymać macierzy K.
Musimy jeszcze sprawdzić, czy model rzeczywiście pasuje do materiału, którym go kalibrowaliśmy.
Wykorzystamy błąd reprojekcji dla każdego ujęcia:
errors = per_view_errors.ravel()
plt.figure(figsize=(12, 4))
plt.bar(range(len(errors)), errors)
plt.xlabel("Numer ujęcia")
plt.ylabel("Błąd reprojekcji [px]")
plt.title("Błąd reprojekcji dla kolejnych klatek")
plt.show()Jeżeli jedno ujęcie ma wyraźnie wyższy błąd od pozostałych, warto sprawdzić, czy nie było rozmyte albo czy plansza została prawidłowo wykryta.
W mojej aplikacji sprawdzam również niepewność oszacowanych parametrów. Przykładowo wysoka niepewność współczynnika k3 może oznaczać, że dane nie pozwalają go dobrze wyznaczyć.
Nie chodzi więc tylko o to, żeby RMS był jak najmniejszy, ale również o to, żeby wynik był stabilny i dobrze sprawdzał się na nowych obrazach.
7. Usuwamy dystorsję ze zdjęcia
Mamy już wszystkie parametry.
Możemy porównać obraz przed i po korekcji dystorsji:
frame = frames[0]
new_K, roi = cv.getOptimalNewCameraMatrix(
K,
dist,
image_size,
1.0,
image_size
)
corrected = cv.undistort(
frame,
K,
dist,
None,
new_K
)
fig, axes = plt.subplots(1, 2, figsize=(12, 6))
axes[0].imshow(cv.cvtColor(frame, cv.COLOR_BGR2RGB))
axes[0].set_title("Przed korekcją")
axes[1].imshow(cv.cvtColor(corrected, cv.COLOR_BGR2RGB))
axes[1].set_title("Po korekcji")
for ax in axes:
ax.axis("off")
plt.show()Warto jednak wiedzieć, że Spatial Maintenance Copilot nie wymaga prostowania każdego obrazu.
Zamiast tego mogę przekazać K i dist bezpośrednio do funkcji solvePnP oraz projectPoints.
Dzięki temu ukryty komponent jest rzutowany na oryginalny obraz z kamery, z uwzględnieniem dystorsji.
8. Zapisujemy wynik do pliku YAML
Nie chcemy przecież kalibrować kamery za każdym razem, kiedy uruchamiamy aplikację.
Dlatego zapisujemy parametry do pliku, który później możemy wykorzystać w Spatial Maintenance Copilot.
fs = cv.FileStorage(
"camera_calibration.yml",
cv.FILE_STORAGE_WRITE
)
fs.write("camera_id", "iphone11-1x-1080p-portrait")
fs.write("image_width", image_size[0])
fs.write("image_height", image_size[1])
fs.write("camera_matrix", K)
fs.write("distortion_coefficients", dist)
fs.write("avg_reprojection_error", float(rms))
fs.write("std_intrinsics", std_intrinsics.ravel()[:9])
fs.release()W pełnym notebooku zapisuję dodatkowo datę, wersję OpenCV oraz liczbę wykorzystanych ujęć - zgodnie ze strukturą mojego projektu.
9. Jak wykorzystuję kalibrację w Spatial Maintenance Copilot?
Na tym etapie kończy się sama kalibracja obiektywu. Ale dla mnie jest to dopiero początek.
W Spatial Maintenance Copilot kolejnym krokiem jest zbudowanie Component Atlas, który przechowuje położenie charakterystycznych punktów szafki oraz ukrytego pudełka w przestrzeni 3D.
Następnie aplikacja przetwarza nowy obraz z telefonu.
OpenCV wykrywa markery ArUco umieszczone na szafce. Ponieważ ich położenia 3D zostały wcześniej zapisane w atlasie, mogę wyznaczyć aktualną pozycję i orientację kamery.
W tym celu wykorzystuję cv.solvePnPRansac i cv.solvePnPRefineLM.
Kiedy znam już pozycję kamery, używam cv.projectPoints, aby przenieść położenie ukrytego pudełka z 3D na współrzędne obrazu.
Co istotne, te obliczenia wykorzystują macierz K i współczynniki dist wyznaczone podczas naszej kalibracji.
Aby nie wyświetlać niepewnej nakładki, aplikacja dodatkowo ocenia jakość lokalizacji i wyznacza region niepewności metodą Monte Carlo. Jeżeli widok jest niewystarczający, agent prosi użytkownika o zmianę pozycji.
Właśnie dlatego poprawna kalibracja jest tak ważna. Stanowi podstawę obliczeń geometrycznych, ale nie zastępuje budowania atlasu, estymacji pozycji kamery ani kontroli niepewności.
Jak to działało w praktyce?
W końcowej ewaluacji demonstratora na zestawie z markerami ArUco mediana błędu lokalizacji ukrytego celu wyniosła 1,7 piksela.
We wcześniejszym wariancie, w którym punkty odniesienia były zaznaczane ręcznie, wynik wynosił 3,4 piksela.
To wyniki całego procesu lokalizacji - nie samej kalibracji.
Dokładniejsze dane znajdziesz w raporcie technicznym Spatial Maintenance Copilot.
Podsumowanie
W tym artykule przeszliśmy przez praktyczny proces kalibracji kamery wykorzystywany w moim projekcie.
Od przygotowania planszy ChArUco, przez nagranie iPhone’em 11 i wykrywanie narożników, aż po wyznaczenie macierzy kamery, współczynników dystorsji oraz zapis do YAML.
Najważniejsze jest jednak to, do czego te dane później wykorzystujemy.
W Spatial Maintenance Copilot kalibracja pozwala prawidłowo interpretować obraz z telefonu i stanowi jeden z fundamentów lokalizowania komponentów, których kamera nie widzi bezpośrednio.
W kolejnym artykule przejdę do solvePnP i pokażę, jak na podstawie punktów 2D i 3D wyznaczyć pozycję telefonu względem urządzenia.
Projekt i kod: Spatial Maintenance Copilot - GitHub
Demonstrator: Spatial Maintenance Copilot - Live Demo