객체 추적

트래킹은 비디오 프레임 전체에서 각 검출에 안정적인 아이덴티티를 할당합니다. LibreYOLO는 이를 자체 가중치를 가진 작업으로 모델링하지 않습니다: 이는 선택된 트래커를 검출, 세분화 또는 포즈 모델의 프레임별 출력 위에서 실행하는 예측 모드인 model.track()입니다.

정의

추적은 LibreYOLO의 작업 키 중 하나가 아니며, 다운로드할 추적 체크포인트도 없습니다. 이는 model.track(source) 모델의 한 메서드로, 각 프레임에서 검출을 실행하고 시간에 따라 결과를 연관시킵니다. 이 메서드는 제너레이터로, 처리된 각 프레임마다 하나의 Results를 생성하며, result.track_id는 result.boxes에 맞춰진 (N,) 정수 텐서로 설정됩니다. 동일한 ID는 result.boxes.id에도 있습니다.

오직 확인된, 현재 추적 중인 객체만 제공됩니다. 추적에서 연관성이 끊어진 객체는 삭제되기 전에 설정된 프레임 수 동안 유지됩니다. ByteTrack와 BoT-SORT의 경우 track_buffer, 두 OC-SORT 변형의 경우 max_age이며, 따라서 그 시간 안에 복구된 객체는 원래의 ID를 유지합니다.

연관은 탐지 후에 발생하기 때문에, 프레임의 다른 페이로드는 영향을 받지 않고 유지됩니다: 추적된 Results는 탐지된 Results에서 일치하는 행으로 잘린 것이므로, 마스크와 키포인트도 박스와 함께 전달됩니다.

모델들

트래킹 실행에는 두 가지 독립적인 선택이 포함됩니다: 각 프레임에서 박스를 생성하는 모델과 박스를 연결하는 트래커입니다.

탐지, 분할 또는 포즈를 수행하는 모든 기본 LibreYOLO 모델은 track()를 노출하므로 탐지기 선택은 일반적인 선택과 동일합니다. 전체 목록은 모델 인덱스를 참조하거나 YOLO9, RF-DETR, D-FINE 또는 RTMDet에서 시작할 수 있습니다. 결과에 연결할 박스가 없는 작업은 무의미한 ID를 반환하지 않고 호출을 거부합니다. 분류, 방향 박스, 포인트, 깊이, 표면 법선, 엣지, 의미론적 및 범주적 분할, 복원, OCR 및 신체 메시 모두 track()에서 예외를 발생시킵니다.

LibreYOLO의 모델 계층 중 두 개도 이를 거부합니다. LibreSAM를 통해 로드된 모델은 이미지 분할기이고, LibreOpenVocab를 통해 로드된 모델은 프레임별 탐지기입니다. 둘 다 track()에서 상속되며 대신 predict()와 함께 프레임별로 사용됩니다.

추적은 네이티브 PyTorch 모델에서 실행됩니다. LibreYOLO("model.onnx")를 통해 로드된 내보낸 아티팩트는 런타임 백엔드 객체를 반환하며, 이 객체는 predict()는 포함하지만 track()는 포함하지 않습니다.

라이브러리에는 tracker 인수로 선택된 네 개의 트래커가 함께 제공됩니다. "bytetrack.yaml" 같은 .yaml 표기는 같은 내장 트래커를 선택하며, LibreYOLO는 트래커 YAML 파일을 읽지 않고 그런 이름의 파일이 작업 디렉터리에 있으면 예외를 발생시킵니다.

"bytetrack"가 기본값입니다. 이는 모션 전용으로, 칼만 필터와 세 단계 연관을 사용합니다: 먼저 높은 신뢰도의 검출, 그런 다음 낮은 신뢰도의 검출이 기존 트랙과 일치할 기회를 제공하는 두 번째 패스가 있으며, 이를 버리기 전에 마지막으로 확인되지 않은 트랙을 처리합니다. TrackConfig로 구성됩니다.

"botsort"는 ByteTrack의 세 단계 수명 주기를 유지하지만, 중심-너비-높이 칼만 상태를 사용하고 매칭 전에 카메라 움직임에 대해 예측된 트랙을 보정합니다. 이것은 BoT-SORT의 움직임 전용 변형이며, 외형 모델을 실행하지 않습니다. BoTSortConfig로 구성되며, 이 구성에는 enable_cmc, cmc_method 및 cmc_downscale가 추가됩니다.

"ocsort"는 또한 모션 전용이며, 연관 비용에 속도-방향 항을 추가하고, 각 트랙의 마지막 실제 관측치에 대해 두 번째 연관 패스를 수행하며, 트랙이 다시 발견될 때 가상 궤적을 따라 칼만 상태를 평활화합니다. OCSortConfig로 구성됩니다.

"deepocsort"는 외형 정보를 활용하여 OC-SORT를 확장합니다. 각 트랙은 재식별 임베딩의 신뢰도 가중 이동 평균을 유지하며, 코사인 유사도 항이 연관 비용에 포함되어, 신원이 긴 가림 현상과 교차 타겟에서도 유지됩니다. 프레임당 작은 임베딩 네트워크 전방 전달 한 번의 비용이 발생하며, OSNet 가중치는 첫 사용 시 다운로드됩니다. DeepOCSortConfig로 구성되어 있습니다.

예측

Python

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # track()는 제너레이터입니다: 처리된 각 프레임마다 하나의 Results를 반환합니다.for result in model.track("video.mp4"):    print(result.track_id)        # (N,) 정수 텐서, 박스와 정렬됨    print(result.boxes.xyxy)

트래커 선택

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # "bytetrack" (기본), "botsort", "ocsort" 또는 "deepocsort".for result in model.track("video.mp4", tracker="botsort"):    print(result.track_id)

주석이 달린 비디오 저장

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # output_path가 없으면 파일은 runs/track/<video_stem>.mp4.에 저장됩니다for result in model.track("video.mp4", save=True, vid_stride=2):    pass

트래커 조정

from libreyolo import BoTSortConfig, LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # 설정 유형이 트래커를 선택하므로 여기서 tracker=는 중복됩니다.config = BoTSortConfig(track_buffer=60, frame_rate=25, enable_cmc=False)for result in model.track("video.mp4", tracker_config=config):    print(result.track_id) # 또는 동일한 필드를 키워드 인수로 전달하고 track()가 그것을 구성하게 하십시오.for result in model.track("video.mp4", tracker="botsort", track_buffer=60):    print(result.track_id)

track_conf는 첫 번째 연관 단계의 임계값을 설정합니다: ByteTrack과 BoT-SORT의 경우 track_high_thresh, OC-SORT와 Deep OC-SORT의 경우 det_thresh입니다. 이것은 predict()의 conf가 아니며, ByteTrack, BoT-SORT 및 OC-SORT의 경우 탐지기는 내부적으로 더 낮은 임계값에서 실행되어 약한 탐지가 복구 단계에서 계속 사용할 수 있도록 합니다. Deep OC-SORT는 탐지기를 det_thresh 자체에서 실행합니다. ByteTrack과 BoT-SORT의 경우 track_conf는 track_low_thresh 이상이어야 하며, 기본값은 0.1입니다.

conf를 지정하면 predict()의 탐지 임계값이 됩니다: 그보다 낮은 탐지는 트래커에 전달되지 않습니다. 지정하지 않으면 탐지기는 위의 임계값에서 실행됩니다.

트래커 설정은 두 가지 방법 중 하나로 이루어집니다. 구성 인스턴스를 tracker_config=에 전달하면, 해당 타입이 트래커를 선택하여 tracker=는 불필요해집니다. 또는 필드를 키워드 인수로 전달하고 track()가 지정한 트래커용 구성을 생성하도록 할 수 있습니다. 알 수 없는 키는 조용히 적용되지 않고 경고를 표시합니다. 어느 쪽이든, 일치하는 키가 명시적으로 설정되면 track_conf는 무시됩니다.

나머지 인수는 예측과 동일합니다. iou, imgsz, classes, max_det, vid_stride, show, 그리고 output_path와 함께 쓰는 save입니다. persist=True는 호출마다 프레임 하나를 전달하는 루프(예: model.track(frame, persist=True))를 위해 같은 모델에서 이전 track() 호출의 트래커와 그 ID를 유지합니다. 소스는 비디오 또는 순서가 있는 이미지 시퀀스일 수 있습니다. 결과 처리는 예측을 참조하십시오.

이미지, 파일 이름순으로 정렬된 폴더, 리스트, 튜플, 지연 이미지 이터레이터를 연속 프레임으로 사용할 수 있습니다. fps=30.0은 시간 간격을 지정하며 color_format="auto"는 입력 해석 방식을 선택합니다. vid_stride는 유지되는 프레임 속도를 fps / vid_stride로 줄입니다.

tracker=로 사용자 정의 추적기 인스턴스를 전달합니다. 인스턴스는 libreyolo.tracking.Tracker의 reset()과 update(results, image=None)을 구현합니다. 실행 시 한 번 초기화하고 원본 RGB PIL 프레임을 전달합니다. 반환하는 track_id는 바운딩 박스와 같은 백엔드/장치에 있고 순서가 일치하는 1차원 정수 배열 또는 텐서여야 합니다. 사용자 정의 인스턴스의 기본값은 track_conf=0.25이며, 추적기 키워드 인수나 tracker_config를 전달하는 대신 인스턴스를 직접 설정합니다.

학습

추적기는 학습되지 않았습니다. 네 대 중 세 대는 학습된 매개변수가 전혀 없는 순수한 모션 모델이며, Deep OC-SORT의 외형 네트워크는 처음 사용할 때 다운로드되는 공개된 재식별 체크포인트입니다. 추적 품질을 향상시키려면 탐지기를 개선하거나 위의 연관 임계값을 조정해야 합니다.