# 7. API 레퍼런스 (API Reference)

> **문서 버전**: 1.0
> **최종 업데이트**: 2025-11-15

---

## 7.1 PowerShell 함수 - PSD-Functions.ps1

### 7.1.1 Get-TemplateMetadataJson

템플릿 메타데이터 JSON 파일을 로드하거나 자동 생성합니다.

**구문**:

```powershell
Get-TemplateMetadataJson -TemplatePath <String> -WorkingDirectory <String>
```

**파라미터**:

| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `TemplatePath` | String | 예 | 템플릿 PSD 파일 경로 |
| `WorkingDirectory` | String | 예 | 작업 디렉토리 경로 |

**반환값**: Hashtable

```powershell
@{
    ImageFilename = "gtwcs.png"
    JsonPath = "/data/working/.../template.json"
    AutoCreated = $false
}
```

**예제**:

```powershell
$metadata = Get-TemplateMetadataJson `
    -TemplatePath "/data/psd_template/.../uuid.psd" `
    -WorkingDirectory "/data/working/20250115-uuid"

Write-Host "Image: $($metadata.ImageFilename)"
```

---

### 7.1.2 Get-ScaledImageDimensions

Fit-to-bounds 알고리즘으로 스케일된 이미지 크기를 계산합니다.

**구문**:

```powershell
Get-ScaledImageDimensions -ImageWidth <Int> -ImageHeight <Int> -BoundWidth <Int> -BoundHeight <Int>
```

**파라미터**:

| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `ImageWidth` | Int | 예 | 원본 이미지 너비 |
| `ImageHeight` | Int | 예 | 원본 이미지 높이 |
| `BoundWidth` | Int | 예 | 대상 영역 너비 |
| `BoundHeight` | Int | 예 | 대상 영역 높이 |

**반환값**: Hashtable

```powershell
@{
    Width = 800
    Height = 600
    OffsetX = 50
    OffsetY = 25
    Scale = 1.2
}
```

**예제**:

```powershell
$dimensions = Get-ScaledImageDimensions `
    -ImageWidth 1000 `
    -ImageHeight 750 `
    -BoundWidth 900 `
    -BoundHeight 700

Write-Host "Scaled: $($dimensions.Width) x $($dimensions.Height)"
```

---

### 7.1.3 Find-MachineNameLayer

PSD 문서에서 머신 이름 텍스트 레이어를 패턴 기반으로 탐색합니다.

**구문**:

```powershell
Find-MachineNameLayer -PsdDocument <Object> -MachineOrder <Int>
```

**파라미터**:

| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `PsdDocument` | Aspose.PSD.Image | 예 | PSD 문서 객체 |
| `MachineOrder` | Int | 예 | 머신 순서 (1, 2, 3...) |

**반환값**: Aspose.PSD.FileFormats.Psd.Layers.Layer 또는 $null

**예제**:

```powershell
$psd = [Aspose.PSD.Image]::Load("template.psd")
$layer = Find-MachineNameLayer -PsdDocument $psd -MachineOrder 1

if ($layer) {
    Write-Host "Found layer: $($layer.Name)"
}
```

---

### 7.1.4 Load-MachineNameImage

머신 이름 PNG 이미지를 로드합니다.

**구문**:

```powershell
Load-MachineNameImage -ImagePath <String>
```

**파라미터**:

| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `ImagePath` | String | 예 | PNG 이미지 파일 경로 |

**반환값**: Aspose.PSD.RasterImage

**예제**:

```powershell
$image = Load-MachineNameImage -ImagePath "/data/machine/107/machine-text/gtwcs.png"
Write-Host "Image size: $($image.Width) x $($image.Height)"
```

---

### 7.1.5 Replace-LayerWithImage

텍스트 레이어를 이미지로 교체합니다.

**구문**:

```powershell
Replace-LayerWithImage -PsdDocument <Object> -Layer <Object> -ImagePath <String>
```

**파라미터**:

| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `PsdDocument` | Aspose.PSD.Image | 예 | PSD 문서 객체 |
| `Layer` | Layer | 예 | 대상 레이어 |
| `ImagePath` | String | 예 | 교체할 이미지 경로 |

**반환값**: Boolean (성공 여부)

**예제**:

```powershell
$success = Replace-LayerWithImage `
    -PsdDocument $psd `
    -Layer $textLayer `
    -ImagePath "/data/working/.../gtwcs.png"

if ($success) {
    Write-Host "Layer replaced successfully"
}
```

---

### 7.1.6 Copy-MachineNameImages

머신 이름 이미지 파일을 작업 디렉토리로 복사합니다.

**구문**:

```powershell
Copy-MachineNameImages -MachineIds <Array> -ImageFilename <String> -WorkingDirectory <String>
```

**파라미터**:

| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `MachineIds` | Array | 예 | 머신 ID 배열 |
| `ImageFilename` | String | 예 | 이미지 파일명 |
| `WorkingDirectory` | String | 예 | 작업 디렉토리 경로 |

**반환값**: Hashtable (복사 결과)

**예제**:

```powershell
$result = Copy-MachineNameImages `
    -MachineIds @(1, 107, 205) `
    -ImageFilename "gtwcs.png" `
    -WorkingDirectory "/data/working/20250115-uuid"

foreach ($machine in $result.Keys) {
    Write-Host "Machine $machine: $($result[$machine])"
}
```

---

### 7.1.7 기타 함수 목록

| 함수명 | 설명 |
|--------|------|
| `Select-Template` | 템플릿 PSD 파일 선택 |
| `Load-PsdDocument` | PSD 파일 로드 |
| `Save-PsdDocument` | PSD 파일 저장 |
| `Place-MachineImage` | 머신 이미지 배치 |
| `Convert-SmartObjectToEmbedded` | 스마트 오브젝트 임베디드 변환 |
| `Validate-TemplateStructure` | 템플릿 구조 검증 |

---

## 7.2 PowerShell 함수 - PSD-Utilities.ps1

### 7.2.1 로깅 함수

#### Write-Log

로그 메시지를 출력합니다.

**구문**:

```powershell
Write-Log -Message <String> -Level <String> [-NoConsole]
```

**파라미터**:

| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `Message` | String | 예 | 로그 메시지 |
| `Level` | String | 예 | `DEBUG`, `INFO`, `WARN`, `ERROR` |
| `NoConsole` | Switch | 아니오 | 콘솔 출력 억제 (JSON 모드) |

**예제**:

```powershell
Write-Log -Message "Processing machine 107" -Level "INFO"
Write-Log -Message "Template not found" -Level "ERROR"
```

---

### 7.2.2 파일 처리 함수

#### New-WorkingDirectory

고유한 작업 디렉토리를 생성합니다.

**구문**:

```powershell
New-WorkingDirectory -BasePath <String>
```

**파라미터**:

| 이름 | 타입 | 필수 | 설명 |
|------|------|------|------|
| `BasePath` | String | 예 | 기본 경로 (예: `/data/working`) |

**반환값**: String (생성된 디렉토리 경로)

**예제**:

```powershell
$workingDir = New-WorkingDirectory -BasePath "/data/working"
# 반환: /data/working/20250115143022-a1b2c3d4
```

---

#### Copy-FileWithValidation

파일 복사 및 검증을 수행합니다.

**구문**:

```powershell
Copy-FileWithValidation -Source <String> -Destination <String>
```

**반환값**: Boolean

---

### 7.2.3 기타 유틸리티 함수

| 함수명 | 설명 |
|--------|------|
| `Get-UniqueIdentifier` | UUID 생성 |
| `Validate-FilePath` | 파일 경로 검증 |
| `Get-Timestamp` | 타임스탬프 생성 |
| `ConvertTo-JsonOutput` | JSON 응답 생성 |

---

## 7.3 설정 파라미터

### 7.3.1 템플릿 디렉토리 경로

**변수**: `$global:TemplateRootPath`

**타입**: String

**설명**: 템플릿 PSD 파일 루트 디렉토리

**예제**:
```powershell
$global:TemplateRootPath = "/data/psd_template"  # Linux
$global:TemplateRootPath = "E:\psd_template"      # Windows
```

---

### 7.3.2 머신 데이터 디렉토리 경로

**변수**: `$global:MachineRootPath`

**타입**: String

**설명**: 머신 데이터 루트 디렉토리

**예제**:
```powershell
$global:MachineRootPath = "/data/machine"  # Linux
$global:MachineRootPath = "E:\poster\machine"  # Windows
```

---

### 7.3.3 작업 디렉토리 경로

**변수**: `$global:WorkingRootPath`

**타입**: String

**설명**: 작업 디렉토리 루트

---

### 7.3.4 로깅 설정

**변수**: `$global:LogLevel`

**타입**: String

**허용값**: `DEBUG`, `INFO`, `WARN`, `ERROR`

**기본값**: `INFO`

---

### 7.3.5 디버그 옵션

**변수**: `$global:DebugMode`

**타입**: Boolean

**기본값**: `$false`

**효과**:
- 상세 로그 출력
- 중간 결과물 보존
- 스택 트레이스 출력

---

## 다음 단계

- **[8. 개발자 가이드](doc_8_developer_guide.md)**: 개발 환경 및 기능 확장
- **[6. 핵심 기능 상세](doc_6_core_features.md)**: 함수 사용 예제

---

**[← 목차로 돌아가기](doc_index.md)**