Dataset Helper

데이터셋의 파일명, 태깅, 단일파일 정리 및 용량절약을위한 webp변환 지원

✨ 주요 기능

0. 기본 사용법

데이터셋이 있는 폴더를 선택하고 병렬처리에 사용할 코어수를 설정합니다.

1. 이름 변경

데이터셋 파일들의 이름을 규칙적으로 정리합니다.

• 이미지-텍스트 쌍(Pair) 유지: 이미지 파일 이름을 변경할 때, 짝이 되는 캡션(.txt) 파일도 자동으로 함께 변경되어 데이터셋의 연결이 끊어지지 않도록 보장합니다.
• 안전한 실행 취소 (Undo): 실수로 이름을 잘못 변경했더라도, 작업 이력을 통해 즉시 이전 상태로 완벽하게 복구할 수 있습니다.
• 실시간 미리보기: 변경될 파일명을 미리 리스트로 확인하여 의도한 대로 변경되는지 검증할 수 있습니다.

2. 단일 파일 찾기

학습에 불필요하거나 오류를 유발할 수 있는 데이터를 정리합니다.

• 짝 없는 파일(Orphan Files) 감지: 캡션 텍스트가 없는 이미지나, 이미지가 없는 텍스트 파일을 자동으로 찾아냅니다.
• 격리 및 삭제: 발견된 파일들을 일괄 삭제하거나, 검토를 위해 별도의 폴더로 이동시킬 수 있습니다.
• 하위 폴더 포함 검색: 옵션을 통해 하위 폴더 깊숙이 숨어있는 파일들까지 모두 스캔합니다.

3. 태그 처리

Danbooru 스타일 태그 및 자연어 캡션을 효율적으로 편집합니다.

• 태그 정렬 및 표준화: 1girl, solo와 같은 핵심 태그를 캡션의 맨 앞으로 이동시킵니다.
• 자동 태그 주입: 캡션에 인원수 정보가 누락된 경우, 설정된 값(성별, 인원수)을 기반으로 태그를 자동 생성하여 추가합니다.
• 인접 태그 수정: 특정 태그를 기준으로 앞이나 뒤에 있는 태그의 접두사/접미사를 수정합니다. (예: b 뒤의 c 앞에 @ 붙이기 -> b, @c)
• CSV 기반 특수 처리: 사용자가 제공한 CSV 파일을 기반으로 특정 카테고리의 태그들을 일괄 추가, 치환, 삭제합니다. (언더바/공백 및 대소문자 무관 정밀 매칭 지원)
• 안전한 실행 취소 (Undo): 태그 처리 작업 후에도 [실행 취소] 버튼을 통해 이전 상태로 복구할 수 있습니다.
• 하위 폴더 포함 검색: 옵션을 통해 하위 폴더에 있는 텍스트 파일까지 한 번에 처리합니다.
• 일괄 편집 기능 (조건부 실행 지원):
  • 치환: 특정 태그를 찾아 오타를 수정하거나 다른 태그로 일괄 변경합니다.
  • 삭제: 학습에 방해되는 불필요한 태그들을 제거합니다. (특정 태그가 있을 때만 삭제하는 조건부 삭제 지원)
  • 추가: 필요한 트리거 워드나 속성 태그를 삽입합니다. (특정 태그가 있을 때만 추가하는 조건부 추가 지원)

4. 이미지 변환

다양한 소스의 이미지를 학습에 최적화된 포맷으로 표준화합니다.

• 입력/출력 폴더 설정: 화면상단에 설정되어있는 작업 폴더 사용하지않습니다. 데이터셋(이미지)이 있는 폴더를 입력 폴더로 설정하고 출력 폴더를 설정합니다.
• 입력 폴더에 출력: 체크박스를 활성화하면 출력 폴더를 별도로 지정하지 않고 입력 폴더에 그대로 저장합니다. 활성화 시 출력 폴더 입력란은 자동으로 비활성화됩니다.
  • 이름 충돌 처리: 입력 폴더에 출력 시 파일명과 확장자가 완전히 겹칠 경우의 처리 방식을 3가지 중 선택합니다. 파일명 접미사가 켜져 있으면 충돌 자체가 발생하지 않으므로 이 옵션은 자동으로 비활성화됩니다.
    • 패스: 충돌이 발생할 파일은 건너뜁니다.
    • 덮어쓰기: 기존 파일을 새 파일로 덮어씁니다.
    • 숫자 추가: 파일명 뒤에 _1, _2 형식으로 숫자를 붙여 충돌을 회피합니다.
• 파일명 접미사 추가: 변환된 이미지의 접미사를 추가합니다.
• 포맷 변환 및 리사이징: JPG, PNG, WEBP 등 다양한 포맷으로의 일괄 변환과 해상도 조절을 지원합니다.
• 메타데이터 보존: 변환 과정에서 손실되기 쉬운 EXIF 정보는 물론, PNG Info (AI 생성 파라미터), Stealth PNG Info까지 감지하여 대상 파일에 최대한 보존합니다.
• 변환 후 원본 삭제: 체크박스를 활성화하면 변환 완료 후 원본 파일을 삭제할 수 있습니다. 삭제 결과(변환 전 파일 수·용량 및 변환 후 파일 수·용량)는 팝업과 로그 모두에 표시됩니다.
  • 확인 팝업 표시: 삭제 전 결과 요약 팝업을 띄워 사용자가 삭제 또는 유지를 직접 선택합니다.
  • 바로 삭제: 팝업 없이 변환 완료 즉시 원본을 자동 삭제합니다.

5. 중복 및 유사 이미지 제거 (Duplicate Finder)

데이터셋의 품질을 저하시키는 중복 데이터를 정밀하게 걸러냅니다.

• 독립 경로 사용: 상단의 공통 작업 폴더 대신, 중복 찾기 탭에서 직접 선택한 별도의 폴더를 독립적으로 검색할 수 있습니다.
• 다중 검색 알고리즘:
  • 완전 중복 (MD5): MD5해시가 동일한 파일을 찾아냅니다.
  • 유사 이미지 (dHash): 해상도가 다르거나 약간의 변형이 있어도 시각적으로 유사한 이미지를 검출합니다.
  • 태그 내용 기반 검색: 이미지뿐만 아니라 짝이 되는 캡션(.txt) 파일의 내용을 분석하여, 태그 구성이 유사한 이미지들을 찾아냅니다. (Jaccard 유사도 활용)
• 유사도 그룹 검색 (Range Search): 지정된 범위(예: 0~3) 내의 모든 유사도 그룹을 한 번에 검색하여 계층적으로 표시합니다.
• 최적화된 성능: Union-Find 알고리즘을 도입하여 범위 검색 시에도 단일 검색과 대등한 빠른 속도를 제공하며, 메인 설정의 '사용 코어' 수를 반영합니다.
• 직관적인 비교 UI: 검출된 중복 그룹/쌍을 직접 비교하며 유지할 파일을 선택하고, 나머지는 삭제하거나 이동할 수 있습니다. (2개 아이템은 '쌍', 3개 이상은 '그룹'으로 표시)
• 이미지 비율 비교: 이미지 비율(Aspect Ratio)이 같은 파일끼리만 비교하도록 설정하여 불필요한 비교를 줄여 검색 속도와 정확도를 높일 수 있습니다.
• 텍스트 파일 동반 처리: 이미지를 삭제하거나 이동할 때, 짝이 되는 캡션 파일(.txt)도 함께 처리하는 옵션을 제공합니다.

6. 데이터셋 분석 (Dataset Analyzer)

학습 효율을 극대화하기 위해 데이터셋의 구성과 학습 스텝을 정밀하게 분석합니다.

• 버킷(Bucket) 분석: 이미지를 학습 시 사용되는 버킷 규격(64단위)으로 분류하여 분포를 보여줍니다. 각 폴더별로 몇 종류의 버킷이 사용되는지([N종]) 한눈에 파악할 수 있습니다.
• 학습 환경 설정: 실제 학습 도구의 메커니즘을 반영하여 기준 해상도(Area), 버킷 크기 단위(Step), 최소/최대 해상도를 사용자가 UI에서 직접 조절할 수 있습니다.
• 정밀 버킷팅 로직: 단순 해상도 반올림 방식이 아닌, 설정된 기준 해상도의 면적(Area)을 유지하며 원본 비율에 가장 적합한 버킷을 찾아 할당합니다. 특히 종횡비가 극단적인 이미지는 유효 범위 밖의 버킷을 강제로 생성하지 않고, 유효한 버킷 중 가장 가까운 비율로 정교하게 배정합니다.
• 버킷 비율 미스매치 감지: 원본 이미지와 배정된 버킷의 종횡비 차이가 큰(30% 초과) 이미지를 자동으로 감지하여 요약 정보에 표시합니다. 전용 팝업 창을 통해 해당 이미지들의 파일명, 해상도, 폴더 경로 등을 리스트업하고 별도의 CSV로 출력하여 학습 데이터 검수에 활용할 수 있습니다. [New]
• 실시간 계산 갱신: 설정을 변경한 후 "분석 (계산 갱신)" 버튼을 누르면, 폴더를 다시 스캔할 필요 없이 메모리에 저장된 이미지 정보를 바탕으로 즉시 버킷 분포, 낭비율, 미스매치 현황이 재계산됩니다.
• 편의 기능 및 리핏 최적화 자동화:
  • 리핏 일괄 설정: 모든 폴더의 리핏을 사용자가 입력한 값으로 한 번에 변경합니다.
  • 추천 리핏 설정: 학습 시간(Step) 균형과 버킷 효율을 동시에 최적화하는 지능형 알고리즘입니다.
  • 최적 리핏 설정: GPU 자원 낭비율을 최소화하는 데 특화된 효율 중심의 설정입니다.
  • 균등 리핏 설정: 모든 폴더의 데이터양을 평균 이상으로 맞추며 최적의 버킷 효율을 찾아냅니다.
• 직관적인 분석 지표:
  • 처리량(이론/실제): 배치로 나누기 전, 이미지 수와 리핏을 곱한 순수 연산량과 버킷 낭비가 포함된 실제 점유 슬롯 수입니다.
  • 스텝(이론/실제): 최종 배치 사이즈를 적용했을 때의 실제 학습 스텝 수입니다.
  • 낭비율: 버킷 규격 불일치로 인해 발생하는 학습 효율 저하를 퍼센트로 표시하며, 테이블 가장 우측에서 최종 결과를 확인할 수 있습니다.
• 결과 CSV 출력: 분석된 전체 요약 정보와 폴더별 상세 내역을 엑셀에서 열 수 있는 CSV 파일(utf-8-sig)로 출력하여 관리할 수 있습니다.
• 데이터셋 스냅샷 [New]: 데이터셋의 구조·수량·용량 정보를 시점별로 저장하고 비교할 수 있는 스냅샷 관리 기능입니다. 자세한 내용은 아래 항목을 참고하세요.

6-1. 데이터셋 스냅샷 (Dataset Snapshot)

학습 데이터셋의 변화를 체계적으로 추적하고 비교합니다.

• 현재 상태 저장: 현재 데이터셋 폴더의 구조, 최하위 폴더 목록, 폴더별 이미지·페어(pair) 수, 총 용량 등 핵심 정보를 JSON 스냅샷으로 저장합니다. 스냅샷 이름과 메모를 함께 입력할 수 있으며, 프로그램 실행 경로의 snapshots/ 폴더에 타임스탬프 기반의 고유 파일명으로 저장되어 덮어쓰기가 발생하지 않습니다. (EXE 패키징 환경 완전 지원)
• 기본 / 비교 스냅샷 불러오기: snapshots/ 폴더의 목록을 드롭다운으로 선택하거나, 파일 탐색기로 직접 경로를 지정해 불러올 수 있습니다.
• 스냅샷 정보 표시: 불러온 스냅샷의 이름, 날짜, 루트 폴더, 총 이미지 수, 짝(pair) 수, 총 용량, 메모를 헤더에 표시하고 최하위 폴더별 상세 정보를 테이블로 보여줍니다.
• 스냅샷 비교하기: 기본 스냅샷과 비교 스냅샷을 나란히 표시하고, 다음 항목을 자동으로 분석합니다.
  • 신규 추가된 폴더 / 삭제된 폴더 목록
  • 경로가 변경되었으나 이름이 같은 폴더의 이동·재구성 감지 (퍼지 매칭)
  • 폴더별 이미지·용량 증감량
  • 전체 이미지·용량 총 증감량 및 증감율(%)
• 유연한 비교 로직: 사용자가 폴더 구조를 크게 개편한 경우에도 최하위 폴더 이름을 기준으로 한 퍼지 매칭을 통해 이동·재구성된 폴더를 감지하여 최대한 의미 있는 비교 결과를 도출합니다.

7. 검색 및 분류 (Search & Filter)

데이터셋 파일을 다양한 조건으로 정밀 검색하고 원하는 방식으로 처리합니다.

• 독립 경로 사용: 상단 공통 작업 폴더 대신, 이 탭에서 직접 지정한 별도의 폴더를 검색 대상으로 사용할 수 있습니다.
• 하위 폴더 포함 검색: 옵션을 통해 하위 폴더까지 재귀적으로 스캔합니다.
• 4가지 검색 조건 (다중 조합 가능):
  • 파일명: 파일명에 특정 문자열이 포함된 파일을 찾습니다.
  • 용량(KB): 최소·최대 용량 범위로 이미지를 필터링합니다.
  • 해상도(px): 너비·높이의 최소·최대 범위로 이미지를 필터링합니다.
  • 태그: .txt 파일 내 태그를 기준으로 검색합니다. 태그는 |로 구분하여 여러 개를 동시에 입력할 수 있습니다.
• 유연한 조건 결합 (라디오 버튼 방식): 각 조건마다 독립적으로 모드를 설정할 수 있습니다.
  • 미사용: 해당 조건을 검색에서 완전히 제외합니다.
  • AND: 이 조건을 반드시 만족해야 합니다.
  • OR: 이 조건을 만족하면 결과에 포함됩니다.
  • NOT: 이 조건에 해당하는 파일을 결과에서 제외합니다.
• 결과 표(Treeview) 및 선택:
  • 검색 결과를 파일명, 확장자, 폴더, 용량, 해상도, 태그 미리보기가 포함된 표로 표시합니다.
  • 파일명·용량·해상도 등 열 헤더 클릭으로 오름차순/내림차순 정렬이 가능합니다.
  • 체크박스로 처리할 항목을 개별 선택하거나, 전체 선택 / 전체 선택해제 버튼으로 일괄 제어합니다.
• 이미지 및 태그 미리보기: 표에서 항목을 클릭하면 우측 하단에 이미지 썸네일과 .txt 태그 파일 내용이 즉시 표시됩니다.
• 3가지 처리 방식:
  • 삭제: 선택한 파일을 영구 삭제합니다.
  • 이동: 선택한 파일을 지정한 폴더로 이동합니다. 파일명 충돌 시 자동으로 _1, _2 접미사를 붙여 안전하게 처리합니다.
  • 복사: 선택한 파일을 지정한 폴더로 복사합니다. 이동과 동일한 충돌 방지 로직이 적용됩니다.
• 처리 대상 선택 (라디오 버튼):
  • 이미지 + 태깅(.txt): 이미지와 연결된 캡션 파일을 세트로 처리합니다.
  • 이미지만: 이미지 파일만 처리하고 캡션 파일은 남겨둡니다.
  • 태깅(.txt)만: 캡션 파일만 처리하고 이미지는 남겨둡니다.
• 짝 없는 파일 발생 경고: 이미지 또는 태깅 중 하나만 처리할 경우, 처리 전 남게 될 고아(Orphan) 파일 목록을 팝업으로 알려줘 의도치 않은 데이터 손실을 방지합니다. (남겨진 고아 파일은 '단일 파일 찾기' 탭에서 추후 정리 가능)

8. XY표 만들기 (XY Plot Builder)

AI 이미지 모델 병합·테스트 결과를 시각적으로 비교하기 위한 XY 비교표를 생성합니다.

• 두 가지 폴더 입력 방식:
  • 셀프 선택: 폴더를 하나씩 추가하여 목록을 구성합니다. 각 폴더 옆에 라벨을 직접 입력할 수 있습니다.
  • 폴더 자동 감지: 상위 폴더를 하나 지정하면 그 안의 하위 폴더들을 자동으로 불러옵니다.
• 빈 칸 채우기 방식: 라디오버튼으로 두 가지 중 선택합니다.
  • 격자 우선: 격자(행 × 열)가 표의 크기를 고정합니다. 폴더나 이미지가 부족한 칸은 NO IMAGE로 채워집니다. (기존 동작과 동일)
  • 데이터 우선: 실제 폴더 수와 폴더 내 최대 이미지 수를 기준으로 표 크기를 자동 결정합니다. 격자 설정값은 무시되며, 폴더마다 이미지 수가 달라 발생하는 NO IMAGE는 정상입니다.
• 이미지 정렬 순서: 기준(이름 / 생성날짜 / 크기)과 방향(오름차순 / 내림차순)을 독립적으로 선택합니다.
• 이미지 배치 방향: 폴더를 행(가로로 펼침) 또는 열(세로로 쌓음) 중 선택합니다. 행↔열 스왑 버튼으로 격자 라벨을 전치하여 재배치합니다.
• 라벨 입력 격자: 행/열 수를 입력하면 Tkinter 격자가 생성되며, 첫 행과 첫 열에 라벨 텍스트를 직접 입력합니다.
  • 격자 생성: 수동으로 입력한 행/열 값으로 격자를 생성합니다.
  • 자동 격자 생성: 현재 설정된 폴더와 그 안의 이미지 수를 분석하여, 데이터를 최대한 담을 수 있는 최적의 행/열(배치 방향에 따라 자동 배분)로 격자를 자동 생성합니다.
• 이미지 셀 크기 모드:
  • 바짝붙이기: 이미지 원본 크기 기준으로 빈틈 없이 배치합니다.
  • 최장변 기준: 전체 이미지 중 가장 긴 변을 한 변으로 하는 정사각형 공간을 각 셀에 확보합니다.
• 혼합 해상도 처리: 이미지 크기가 다를 경우 기준(최대 / 최소 / 직접 지정)을 선택하고, 처리 방식(스케일[종횡비 유지+레터박스] / 크롭[중앙 기준])을 선택합니다.
• 제목: 체크박스로 활성화하며 표 상단 중앙에 표시됩니다. 글자 크기는 자동 또는 직접 지정할 수 있습니다.
• 라벨 글자: 크기 모드(자동 / 핏 / 직접 설정)와 가로·세로 정렬을 개별 설정합니다.
• 패딩 / 스케일조절: 셀 간 여백(px)과 전체 출력 이미지 축소 비율(%)을 설정합니다. 이미지·라벨·제목·여백 등 모든 요소가 비율에 맞게 조정됩니다.
• 저장 옵션: PNG / WEBP / JPG 포맷 선택, 무손실·손실 압축 및 품질 설정, 저장 경로 지정. 동일 파일명 존재 시 덮어쓰기 여부를 확인합니다.
• 미리보기: 별도 창으로 열리며, 완성본을 먼저 렌더링한 뒤 축소하여 표시하므로 실제 결과와 정확히 일치합니다. 마우스 휠·드래그로 확대/축소·이동이 가능하며, 미리보기 저장과 완성본 저장 버튼을 제공합니다.

💡 학습 전략 가이드 (추천 설정 매트릭스)

사용자의 그래픽카드 체급과 보유한 데이터셋 규모에 따른 권장 설정입니다. 자신의 상황에 맞는 버튼을 선택하여 학습 효율을 극대화하세요.

데이터셋 규모	하이엔드 (High-end)	메인스트림 (Mainstream)	엔트리 (Entry-level)
소규모 (< 500장)	최적 리핏 설정	최적 리핏 설정	추천 리핏 설정
중규모 (500 ~ 1만장)	최적 리핏 설정	추천 리핏 설정	균등 리핏 설정
대규모 (> 1만장)	추천 리핏 설정	균등 리핏 설정	균등 리핏 설정

• 최적 리핏 설정: GPU 자원을 100% 가깝게 활용하여 가장 정밀한 학습 결과를 원할 때 선택하세요. (낭비율 최저)
• 추천 리핏 설정: 학습 시간과 결과물 품질의 균형이 가장 잘 잡힌 표준 설정입니다. (밸런스 최적)
• 균등 리핏 설정: 학습 시간을 약 30% 이상 단축하여 빠른 피드백을 원할 때 매우 유용합니다. (속도 최상)

---

🛠 설치 및 실행 방법

요구 사항

• Python 3.8 이상
• Windows 운영체제

설치 및 실행

• 직접 실행 : Dataset-Helper-(버전).exe를 실행합니다
• 클론 실행 :

1. 이 저장소를 다운로드하거나 클론합니다.
2. 필요한 패키지를 설치합니다. (requirements.txt 참고)
3. 프로그램을 실행합니다 (main.py)

💡 사용 팁 (Tips)

• 중복 찾기 범위 검색: '유사도 그룹 검색'을 사용하면 여러 단계의 유사도를 한 번에 확인할 수 있어 데이터셋에 최적인 필터링 값을 찾기 매우 용이합니다. 시작값이 종료값보다 크더라도 프로그램이 자동으로 순서를 교정하여 검색합니다.
• 멀티코어 설정: '이미지 변환'이나 '태그 처리' 시 코어 수를 높이면 속도가 빨라지지만 다른 작업(웹 서핑 등)이 느려질 수 있습니다. 원활한 멀티태스킹을 원하시면 전체 코어 수보다 2~4개 적게 설정하는 것을 권장합니다.
• 검색 및 분류 - 조건 조합: AND 조건은 '이 파일은 반드시 포함', OR 조건은 '이 중 하나라도 해당하면 포함', NOT 조건은 '이 조건에 해당하면 제외'로 동작합니다. 예를 들어 "용량 AND(100KB 이상) + 태그 NOT(simple background 포함)"으로 설정하면 100KB 이상이면서 단순 배경 태그가 없는 파일만 걸러낼 수 있습니다.
• 검색 및 분류 - 해상도 검색 속도: 해상도 조건 사용 시 이미지 파일을 직접 열어 읽기 때문에 파일 수가 많을수록 검색 시간이 길어집니다. 상단의 '사용 코어' 수를 높이면 병렬 처리로 속도를 크게 향상시킬 수 있습니다.