class AprilTag – AprilTag 객체

apriltag 객체는 Image.find_apriltags()가 반환하는 attrtuple입니다. 각 인스턴스는 디코딩된 AprilTag를 기술합니다: 경계 상자, 서브픽셀 중심점, 패밀리/id, 디코더 품질 지표, 검출된 네 모서리, 그리고 – Image.find_apriltags()에 내부 파라미터가 제공된 경우 – 카메라 프레임에서의 6자유도 자세 추정값을 포함합니다.

필드는 속성 이름(tag.id) 또는 인덱스(tag[0])로 접근할 수 있습니다. 이 객체에는 공개 생성자가 없습니다.

class image.apriltag

이 객체를 생성하려면 Image.find_apriltags()를 호출하세요.

경계 상자와 모서리

x

경계 상자의 왼쪽 상단 x 좌표(픽셀). 정수. 인덱스 [0].

y

경계 상자의 왼쪽 상단 y 좌표(픽셀). 정수. 인덱스 [1].

w

경계 상자의 너비(픽셀). 정수. 인덱스 [2].

h

경계 상자의 높이(픽셀). 정수. 인덱스 [3].

cx

정수로 반올림된 중심점 x 좌표. 정수. 인덱스 [4].

cy

정수로 반올림된 중심점 y 좌표. 정수. 인덱스 [5].

cxf

서브픽셀 float 형식의 중심점 x 좌표. 인덱스 [9].

cyf

서브픽셀 float 형식의 중심점 y 좌표. 인덱스 [10].

corners

태그의 검출된 네 모서리에 대한 (x, y) 정수 튜플로 이루어진 4-튜플로, 왼쪽 상단 모서리부터 시작하여 시계 방향으로 정렬됩니다. 인덱스 [21].

area

경계 상자의 면적(w * h). 정수. 인덱스 [22].

rect

경계 상자의 (x, y, w, h) 4-튜플. Image.draw_rectangle()이나 Image.crop() 같은 그리기/자르기 메서드에 직접 전달하기에 적합합니다. 인덱스 [23].

식별

id

패밀리 내에서 태그의 숫자 id. 유효 범위는 패밀리에 따라 다릅니다(예: TAG36H11의 경우 0 – 586). 정수. 인덱스 [6].

family

숫자 패밀리 식별자로, 다음 중 하나입니다:

정수. 인덱스 [7].

name

문자열 형식의 패밀리 이름, 예: "TAG36H11". 인덱스 [8].

매칭 품질

decision_margin

0.0 – 1.0 범위의 태그 매칭 품질로, 1.0이 가장 좋습니다. 신뢰도가 낮은 검출을 걸러내는 데 사용하세요. Float. 인덱스 [12].

hamming

이 태그에 대해 디코더가 허용한 비트 오류 수. 패밀리의 정정 능력에 의해 제한됩니다:

  • TAG16H5 -> 최대 0개의 비트 오류

  • TAG25H9 -> 최대 3개의 비트 오류

  • TAG36H10 -> 최대 3개의 비트 오류

  • TAG36H11 -> 최대 4개의 비트 오류

낮을수록 좋습니다. 정수. 인덱스 [13].

goodness

0.0 – 1.0 범위의 태그 이미지 품질로, 1.0이 가장 좋습니다. 현재 출시된 펌웨어에서는 항상 0.0입니다(내부 디코더가 더 이상 이 지표를 계산하지 않음). Float. 인덱스 [14].

자세 추정

아래의 평행 이동 및 회전 필드는 Image.find_apriltags()가 fx, fy, cx, cy 카메라 내부 파라미터와 함께 호출된 경우에만 채워집니다. 내부 파라미터가 없으면 0.0입니다. 태그는 너비가 1단위라고 가정하므로, 평행 이동은 “태그 너비” 단위입니다 – 실제 거리를 얻으려면 실세계의 태그 크기로 스케일링하세요.

x_translation

카메라로부터의 X 평행 이동(좌우), 태그 너비 단위. Float. 인덱스 [15].

y_translation

카메라로부터의 Y 평행 이동(상하), 태그 너비 단위. Float. 인덱스 [16].

z_translation

카메라로부터의 Z 평행 이동(앞뒤), 태그 너비 단위. Float. 인덱스 [17].

x_rotation

X축에 대한 회전(피치), 라디안 단위. Float. 인덱스 [18].

y_rotation

Y축에 대한 회전(요), 라디안 단위. Float. 인덱스 [19].

z_rotation

Z축에 대한 회전(롤), 라디안 단위. rotation과 동일한 값으로, x_rotation, y_rotation과의 대칭을 위해 중복됩니다. Float. 인덱스 [20].

rotation

이미지 평면 내에서의 태그 회전, 라디안 단위. z_rotation과 같습니다. Float. 인덱스 [11].