UI 테스트나 화면 분석 작업에서 스크린샷 속 요소를 자동으로 식별해야 하는 상황이 자주 발생한다. VideoAgentTrek Screen Filter는 이런 니즈를 해결해주는 시각적 객체 탐지 솔루션으로, 별도의 코딩 없이 브라우저에서 직접 동작한다. YOLO v8 아키텍처를 기반으로 화면 콘텐츠에 특화된 학습이 적용되어 있어, 버튼, 입력 필드, 아이콘 등 인터페이스 구성요소를 높은 정확도로 찾아낸다.
1. 설치 및 실행
1.1 사전 준비
도커 컨테이너 형태로 패키징되어 있어 별도의 파이썬 환경 구성이 불필요하다. 다음 조건만 충족하면 즉시 사용 가능하다.
- 지원 환경: 리눅스, 윈도우(WSL2), macOS
- 컨테이너 런타임: Docker 또는 Docker Desktop 설치 완료
- 권장 사양: 메모리 4GB 이상, CUDA 지원 그래픽 카드(선택사항)
1.2 서비스 기동
단일 명령어로 웹 서버를 구동한다.
python3 /root/VideoAgentTrek-ScreenFilter/app.py실행 성공 시 터미널에 다음 메시지가 출력된다.
Running on local URL: http://0.0.0.0:7860
To create a public link, set `share=True` in `launch()`브라우저에서 http://localhost:7860로 접속하면 대시보드가 표시된다. 부 기기에서 접근하려면 호스트 머신의 IP 주소로 교체하면 된다.
2. 인터페이스 활용법
2.1 패널 구성
화면은 세 개의 기능 영역으로 구분된다.
- 좌측 업로드 영역: 이미지 파일 선택 및 등록
- 중앙 제어 영역: 분석 실행 버튼과 옵션 설정
- 우측 결과 영역: 시각화된 탐지 결과와 상세 데이터 표시
2.2 이미지 등록
업로드 영역을 클릭해 스크린샷을 선택한다. 지원 포맷은 다음과 같다.
- PNG: 무손실 압축, UI 캡처에 최적
- JPEG: 손실 압축, 파일 크기가 작음
- BMP: 무압축, 원본 품질 유지
권장 설정: PNG 포맷, 해상도 800×600 ~ 1920×1080 범위, 텍스트가 선명하게 보이는 화질
2.3 객체 탐지 실행
중앙의 "🔍 분석 시작" 버튼을 누르면 추론이 시작된다. 소요 시간은 하드웨어에 따라 상이하다.
- CPU 전용: 800×600 이미지당 약 1~3초
- GPU 가속: 동일 조건에서 5~10배 단축
2.4 결과 확인
분석 완료 후 우측에 두 가지 출력물이 나타난다.
시각화 이미지: 원본 위에 바운딩 박스가 겹쳐 표시되며, 클래스명과 신뢰도 점수가 함께 표기된다.
상세 데이터 테이블:
| 항목 | 설명 | 예시 |
|---|---|---|
| 클래스 | 식별된 객체 유형 | button, input_field, icon |
| 신뢰도 | 모델 확신 정도 | 0.94 (94%) |
| 좌측 상단 X | 박스 시작점 가로 좌표 | 135 |
| 좌측 상단 Y | 박스 시작점 세로 좌표 | 95 |
| 너비 | 박스 가로 길이(픽셀) | 75 |
| 높이 | 박스 세로 길이(픽셀) | 35 |
신뢰도 0.7 이상인 결과는 일반적으로 안정적인 편이다.
3. 활용 시나리오
3.1 자동화 테스트 연계
탐지된 좌표 정보를 테스트 스크립트에 활용할 수 있다.
# 좌표 기반 클릭 자동화 예시
from selenium import webdriver
from selenium.webdriver.common.action_chains import ActionChains
# 탐지 결과: 버튼 위치 (x=135, y=95, w=75, h=35)
pos_x, pos_y, box_w, box_h = 135, 95, 75, 35
center_x = pos_x + box_w // 2
center_y = pos_y + box_h // 2
driver = webdriver.Chrome()
actions = ActionChains(driver)
actions.move_by_offset(center_x, center_y).click().perform()3.2 디자인 검증
UI/UX 작업자에게 유용한 활용 방식:
- 동일 기능 요소의 페이지 간 위치 일관성 점검
- 요소 간 간격이 디자인 가이드에 부합하는지 확인
- 화면 복잡도 분석을 통한 사용자 경험 평가
3.3 대량 콘텐츠 분석
사용자 행동 연구, 경쟁 제품 비교, 콘텐츠 심사 등에서 다량의 스크린샷을 효율적으로 처리한다.
4. 기술적 배경
4.1 YOLO v8 기반 탐지 엔진
Ultralytics YOLO v8을 채택하여 단일 순전파로 객체 위치와 클래스를 동시 예측한다. 화면 콘텐츠 특성에 맞춰 다음과 같이 최적화되었다.
- 인터페이스 전용 클래스 정의
- UI 요소 시각적 특징 강조된 특성 추출
- 비인터페이스 영역에 대한 오탐지 억제
학습된 가중치는 /root/ai-models/xlangai/VideoAgentTrek-ScreenFilter/best.pt에 위치한다.
4.2 성능 지표
| 하드웨어 | 처리 속도(800×600) | 특이사항 |
|---|---|---|
| Intel i5 (CPU) | 1~3초/장 | 소규모 작업용 |
| GTX 1060 | 0.2~0.5초/장 | 배치 처리 적합 |
| RTX 3080 | 0.1~0.3초/장 | 고성능 워크로드 |
5. 고급 활용 기법
5.1 다건 일괄 처리
HTTP API를 호출하여 폴더 내 이미지를 순차 처리한다.
import os, json, requests
from pathlib import Path
def process_directory(img_dir: str, endpoint: str = "http://localhost:7860/detect"):
outcomes = {}
img_paths = Path(img_dir).glob("*")
valid_exts = {'.png', '.jpg', '.jpeg', '.bmp'}
for img_path in img_paths:
if img_path.suffix.lower() not in valid_exts:
continue
with open(img_path, 'rb') as stream:
resp = requests.post(
endpoint,
files={'screenshot': (img_path.name, stream, 'image/png')}
)
if resp.status_code == 200:
payload = resp.json()
outcomes[img_path.name] = payload
print(f"완료: {img_path.name} - {len(payload['items'])}개 탐지")
with open("batch_results.json", 'w', encoding='utf-8') as out:
json.dump(outcomes, out, ensure_ascii=False, indent=2)
return outcomes
if __name__ == "__main__":
process_directory("./captures")5.2 임계값 동적 조정
기본 임계값(0.25)을 상황에 맞게 변경한다.
# API 호출 시 파라미터 전달
def detect_with_threshold(image_path: str, cutoff: float = 0.6):
with open(image_path, 'rb') as f:
resp = requests.post(
"http://localhost:7860/detect",
files={'image': f},
data={'confidence': cutoff}
)
return resp.json()
# 또는 app.py 소스 수정
def run_inference(frame, weights_path, confidence_floor=0.25):
detector = YOLO(weights_path)
return detector(frame, conf=confidence_floor)임계값 선택 가이드: 0.7~0.9(정밀도 우선), 0.4~0.6(균형), 0.2~0.3(재현율 우선)
5.3 결과 데이터 내보내기
JSON 구조:
{
"source": "capture_001.png",
"findings": [
{"type": "submit_btn", "score": 0.91, "coords": [135, 95, 210, 130]},
{"type": "search_field", "score": 0.88, "coords": [250, 200, 450, 235]}
],
"meta": {"detected_count": 2, "mean_score": 0.895}
}CSV 형식:
source_file,element_type,confidence,x1,y1,width,height
capture_001.png,submit_btn,0.91,135,95,75,35
capture_001.png,search_field,0.88,250,200,200,356. 문제 해결
| 증상 | 원인 분석 | 해결 방안 |
|---|---|---|
| 탐지 결과 없음 | 이미지 품질, 임계값 과다, 빈 화면 | 선명도 확인, 임계값 하향, 다른 이미지 시험 |
| 정확도 저조 | 특수 UI 패턴, 학습 데이터 부족 | 사후 필터링, 수동 검증, 파인튜닝 |
| 처리 지연 | CPU 병목, 고해상도 입력 | GPU 활성화, 이미지 리사이즈, 하드웨어 업그레이드 |
| 미지원 클래스 | 학습 범위 초과 | 신규 데이터 수집·라벨링, 전이학습 |
7. 정리
VideoAgentTrek Screen Filter는 복잡한 딥러닝 파이프라인을 웹 인터페이스로 단순화한 실용적 도구다. 코딩 없는 즉시 사용, 화면 특화 정확도, 범용 하드웨어 호환성을 갖추어 개발, 테스트, 디자인 분야의 다양한 워크플로우에 통합할 수 있다.
초기 사용 시 간단한 스크린샷으로 흐름을 익힌 후, 임계값 튜닝과 배치 처리를 점진적으로 적용하는 것을 권장한다. 탐지 결과를 체계적으로 축적하면 조직의 UI 컴포넌트 데이터베이스 구에도 활용 가능하다.