Loading
Menu
ARTICLE
Computer vision5 min read

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.

Ilustracja stanowiska kalibracji kamery: telefon skierowany na planszę ChArUco i laptop z wykrywaniem narożników w OpenCV.
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ą.

Parametry planszy użytej do kalibracji mojego iPhone’a 11:
ParametrWartość
Układ5 x 7 kwadratów
Bok kwadratu30 mm
Bok markera21,6 mm
Słownik DICT_5X5_100
ID markerów0-16
Rozmiar planszy150 x 210 mm

Możemy wygenerować jej model w Pythonie:

charuco_board.pypython
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:

Codepython
import cv2 as cv
import numpy as np
import matplotlib.pyplot as plt

print(cv.__version__)

Teraz możemy wgrać nagranie z telefonu:

Codepython
from google.colab import files

uploaded = files.upload()

Następnie pobieramy z niego klatki, które zostaną wykorzystane do kalibracji:

Codepython
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:

Codepthon
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.

Codepython
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:

Codepython
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ęć.

Codepython
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:

Codepython
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:

Codepython
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:

Codepython
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.

Codepython
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

Sources & further reading

  1. 1.Poprzedni artykuł: Kalibracja kamery i dystorsja obiektywu - wprowadzenie do teorii., Łukasz Olszewski
  2. 2.Repozytorium: Spatial Maintenance Copilot - rzeczywisty kod oraz wyniki eksperymentu., Łukasz Olszewski

Contact

Open to frontend, full-stack and AI engineering roles. B2B, Warsaw or remote.

lukols.dev@gmail.com
Email me

Let's work
together

Łukasz©2026
Olszewski