# 3. 데이터 준비 (Data Preparation) > **문서 버전**: 1.0 > **최종 업데이트**: 2025-11-15 --- ## 3.1 poster.csv 데이터 구조 ### 3.1.1 CSV 파일 개요 `poster.csv`는 포스터 생성에 사용할 머신(기계) 정보를 저장하는 CSV 파일입니다. 각 머신의 ID, 이름, 카테고리 등의 메타데이터를 포함합니다. **파일 위치**: 프로젝트 루트 디렉토리 (`./poster.csv`) **문자 인코딩**: UTF-8 (BOM 없음 권장) **구분자**: 쉼표 (`,`) --- ### 3.1.2 컬럼 정의 및 데이터 타입 #### 필수 필드 | 컬럼명 | 데이터 타입 | 설명 | 예시 | |--------|------------|------|------| | `id` | Integer | 머신 고유 ID (Primary Key) | `1`, `107`, `205` | | `name` | String | 머신 이름 (일본어/한국어) | `スロット太郎`, `파칭코왕` | | `category` | String | 머신 카테고리 | `パチンコ`, `スロット` | #### 선택 필드 | 컬럼명 | 데이터 타입 | 설명 | 기본값 | |--------|------------|------|-------| | `maker` | String | 제조사 | - | | `release_date` | Date | 출시일 (YYYY-MM-DD) | - | | `spec` | String | 스펙 정보 | - | | `image_path` | String | 이미지 파일 경로 (상대) | `/data/machine/{id}/` | #### 데이터 제약사항 - `id`: 양의 정수, 중복 불가, 1 이상 - `name`: 빈 문자열 불가, 최대 100자 - `category`: 빈 문자열 불가 - `release_date`: `YYYY-MM-DD` 형식 (예: `2024-03-15`) --- ### 3.1.3 샘플 데이터 예제 ```csv id,name,category,maker,release_date,spec,image_path 1,エヴァンゲリオン,パチンコ,ビスティ,2024-01-10,確変タイプ,/data/machine/1/ 107,沖ドキ!,スロット,アクロス,2023-11-20,A+ART,/data/machine/107/ 205,北斗の拳,パチンコ,サミー,2024-02-15,確変タイプ,/data/machine/205/ 312,まどマギ,スロット,メーシー,2023-12-01,AT,/data/machine/312/ ``` --- ### 3.1.4 CSV 파일 작성 가이드 #### Excel에서 작성하기 1. Excel에서 데이터 입력 2. "다른 이름으로 저장" → "CSV UTF-8 (쉼표로 분리)" 선택 3. `poster.csv`로 저장 #### 텍스트 에디터에서 작성하기 ```csv id,name,category 1,エヴァンゲリオン,パチンコ 107,沖ドキ!,スロット ``` **주의사항**: - UTF-8 인코딩으로 저장 - 쉼표(`,`)가 데이터에 포함된 경우 큰따옴표로 감싸기: `"이름,부제"` - 줄바꿈은 `\n` (LF) 권장 #### PowerShell에서 CSV 확인 ```powershell # CSV 파일 읽기 Import-Csv -Path "./poster.csv" -Encoding UTF8 # 특정 머신 ID 검색 Import-Csv -Path "./poster.csv" -Encoding UTF8 | Where-Object { $_.id -eq "107" } ``` --- ## 3.2 템플릿 준비 ### 3.2.1 템플릿 디렉토리 구조 템플릿 PSD 파일은 다음과 같은 계층 구조로 저장됩니다: ``` /data/psd_template/ ├── vertical/ # 세로 방향 템플릿 │ ├── grandOpen/ # 그랜드오픈 로고타입 │ │ ├── machine_1/ # 머신 1대용 │ │ ├── machine_2/ # 머신 2대용 │ │ └── machine_3/ # 머신 3대용 │ ├── renewalOpen/ # 리뉴얼오픈 로고타입 │ ├── newOpen/ │ ├── refreshOpen/ │ └── newMachineReplacement/ └── horizontal/ # 가로 방향 템플릿 ├── grandOpen/ ├── renewalOpen/ └── ... ``` #### 세부 디렉토리 구조 예시 ``` /data/psd_template/vertical/grandOpen/machine_1/m1/s0/ └── 36cc0517-bc80-43b7-9ff6-bd947b2136e7/ ├── 36cc0517-bc80-43b7-9ff6-bd947b2136e7.psd # 템플릿 PSD 파일 └── 36cc0517-bc80-43b7-9ff6-bd947b2136e7.json # 메타데이터 JSON ``` --- ### 3.2.2 템플릿 파일 명명 규칙 템플릿 파일은 UUID를 사용하여 고유하게 식별됩니다: - **PSD 파일**: `{uuid}.psd` - **JSON 메타데이터**: `{uuid}.json` 예시: - `36cc0517-bc80-43b7-9ff6-bd947b2136e7.psd` - `36cc0517-bc80-43b7-9ff6-bd947b2136e7.json` --- ### 3.2.3 템플릿 메타데이터 JSON #### JSON 파일 구조 템플릿 PSD 파일과 동일한 디렉토리에 JSON 메타데이터 파일을 배치합니다. **파일명**: 템플릿 PSD와 동일한 이름 (확장자만 `.json`) **기본 스키마**: ```json { "machine_name_image": "gtwcs.png" } ``` #### 필드 설명 | 필드 | 타입 | 설명 | 예시 | |------|------|------|------| | `machine_name_image` | String | 머신 이름 텍스트 이미지 파일명 | `"gtwcs.png"`, `"mtwcs.png"` | #### 예제 **36cc0517-bc80-43b7-9ff6-bd947b2136e7.json** ```json { "machine_name_image": "gtwcs.png" } ``` 이 설정은 모든 머신 이름 레이어를 `gtwcs.png` 이미지로 교체하도록 지시합니다. #### 기본값 및 자동 생성 JSON 파일이 없으면 시스템이 자동으로 기본값(`gtwcs.png`)을 사용하고, working directory에 JSON 파일을 생성합니다. **자동 생성된 JSON 예시**: ```json { "machine_name_image": "gtwcs.png" } ``` **로그 메시지**: ``` [WARN] Template metadata JSON not found, using default: gtwcs.png [INFO] Created template metadata JSON in working directory ``` --- ## 3.3 머신 데이터 준비 ### 3.3.1 머신 데이터 디렉토리 구조 각 머신은 고유한 디렉토리를 가지며, 이미지 및 텍스트 파일을 포함합니다. **표준 레이아웃**: ``` /data/machine/{machineId}/ ├── main.png # 메인 이미지 ├── sub1.png # 서브 이미지 1 ├── sub2.png # 서브 이미지 2 └── machine-text/ # 머신 이름 텍스트 이미지 ├── gtwcs.png # Gothic, Transparent, White, Center, Single-line ├── mtwcs.png # Mincho, Transparent, White, Center, Single-line └── gtwcl.png # Gothic, Transparent, White, Center, Left-align ``` #### 실제 예시 **머신 ID 107**: ``` /data/machine/107/ ├── main.png ├── sub1.png ├── sub2.png └── machine-text/ ├── gtwcs.png ├── mtwcs.png └── gtwcl.png ``` --- ### 3.3.2 머신 이미지 파일 #### 이미지 파일 요구사항 | 항목 | 요구사항 | |------|---------| | 파일 형식 | PNG (권장), JPEG | | 해상도 | 300 DPI 이상 권장 | | 색상 모드 | RGB | | 투명도 | PNG 알파 채널 지원 | | 파일 크기 | 10MB 이하 권장 | #### 파일명 규칙 - `main.png`: 메인 머신 이미지 - `sub1.png`, `sub2.png`: 추가 이미지 (옵션) --- ### 3.3.3 machine-text 디렉토리 #### 머신 이름 이미지 파일 템플릿의 텍스트 레이어를 대체할 사전 렌더링된 PNG 이미지입니다. #### 파일명 규칙 파일명은 다음 규칙을 따릅니다: **형식**: `{폰트}{t}{w}{정렬}{s}.png` | 코드 | 의미 | 옵션 | |------|------|------| | 폰트 | 폰트 종류 | `g` (Gothic), `m` (Mincho) | | `t` | Transparent (투명 배경) | 항상 `t` | | `w` | White (흰색 텍스트) | 항상 `w` | | 정렬 | 정렬 방식 | `c` (Center), `l` (Left) | | `s` | Single-line (단일 라인) | 항상 `s` | #### 파일 종류 1. **gtwcs.png** - **Gothic** 폰트 - **Transparent** 배경 - **White** 텍스트 - **Center** 정렬 - **Single-line** 2. **mtwcs.png** - **Mincho** 폰트 - Transparent 배경 - White 텍스트 - Center 정렬 - Single-line 3. **gtwcl.png** - **Gothic** 폰트 - Transparent 배경 - White 텍스트 - **Left** 정렬 - Single-line #### 이미지 사양 | 항목 | 요구사항 | |------|---------| | 파일 형식 | PNG | | 배경 | 투명 (알파 채널) | | 텍스트 색상 | 흰색 (#FFFFFF) | | 해상도 | 템플릿 레이어 크기에 맞게 | | 여백 | 최소화 (텍스트 경계에 가깝게) | #### 이미지 준비 방법 **방법 1: Photoshop에서 생성** 1. 새 문서 생성 (투명 배경) 2. 텍스트 레이어 추가 (흰색, 해당 폰트) 3. 텍스트 입력: 머신 이름 4. "파일" → "내보내기" → "PNG로 빠른 내보내기" 5. `gtwcs.png`로 저장 **방법 2: GIMP에서 생성** 1. 새 이미지 (투명도 활성화) 2. 텍스트 도구로 머신 이름 입력 3. PNG로 내보내기 **방법 3: ImageMagick 명령줄** ```bash # Gothic 폰트, 중앙 정렬, 투명 배경 convert -background transparent \ -fill white \ -font "Gothic-Font.ttf" \ -pointsize 72 \ -gravity center \ label:"沖ドキ!" \ gtwcs.png ``` --- ## 데이터 준비 체크리스트 ### poster.csv - [ ] UTF-8 인코딩으로 저장 - [ ] 필수 컬럼 포함 (`id`, `name`, `category`) - [ ] ID 중복 없음 - [ ] 데이터 형식 검증 완료 ### 템플릿 - [ ] 템플릿 PSD 파일 배치 완료 - [ ] 템플릿 메타데이터 JSON 생성 (또는 자동 생성 허용) - [ ] 템플릿 디렉토리 구조 확인 ### 머신 데이터 - [ ] 각 머신 ID별 디렉토리 생성 - [ ] 메인 이미지 파일 배치 - [ ] machine-text 디렉토리 생성 - [ ] 머신 이름 이미지 (gtwcs.png 등) 준비 --- ## 다음 단계 - **[4. 사용 가이드](doc_4_user_guide.md)**: 데이터를 활용한 포스터 생성 방법 - **[10. 데이터 스키마 레퍼런스](doc_10_data_schema.md)**: 상세한 스키마 정의 --- **[← 목차로 돌아가기](doc_index.md)**