mirror of
https://github.com/snapotter-hq/SnapOtter.git
synced 2026-08-03 07:46:42 +02:00
SnapOtterandGitHub
4963ab3bbd
All 181 docs markdown files translated into 20 languages (apps/docs/<locale>/**). Companion to the i18n code PR; admin-merged because the file count exceeds GitHub's per-PR CI trigger limit. Validated by pnpm i18n:check (all surfaces, 0 stale/missing) and a clean all-locale docs build.
212 lines
9.1 KiB
Markdown
212 lines
9.1 KiB
Markdown
---
|
|
description: "이미지 엔진 작업 레퍼런스. 모든 Sharp 기반 이미지 처리 작업과 매개변수."
|
|
i18n_source_hash: 42febdf85fa8
|
|
i18n_provenance: human
|
|
i18n_output_hash: 9a40c4b2dc21
|
|
---
|
|
|
|
# 이미지 엔진 {#image-engine}
|
|
|
|
`@snapotter/image-engine` 패키지는 AI가 아닌 모든 이미지 작업을 처리합니다. 이 패키지는 [Sharp](https://sharp.pixelplumbing.com/)를 감싸며, 외부 의존성 없이 프로세스 내에서 완전히 실행됩니다.
|
|
|
|
## 작업 {#operations}
|
|
|
|
### resize {#resize}
|
|
|
|
이미지를 특정 치수 또는 백분율로 확대/축소합니다.
|
|
|
|
| 매개변수 | 타입 | 설명 |
|
|
|---|---|---|
|
|
| `width` | number | 목표 너비(픽셀) |
|
|
| `height` | number | 목표 높이(픽셀) |
|
|
| `fit` | string | `cover`, `contain`, `fill`, `inside`, 또는 `outside` |
|
|
| `withoutEnlargement` | boolean | true이면 더 작은 이미지를 확대하지 않음 |
|
|
| `percentage` | number | 절대 치수 대신 백분율로 확대/축소 |
|
|
|
|
`width`, `height` 또는 둘 다 설정할 수 있습니다. 하나만 설정하면 나머지는 종횡비를 유지하도록 계산됩니다.
|
|
|
|
### crop {#crop}
|
|
|
|
이미지에서 직사각형 영역을 잘라냅니다.
|
|
|
|
| 매개변수 | 타입 | 설명 |
|
|
|---|---|---|
|
|
| `left` | number | 왼쪽 가장자리로부터의 X 오프셋 |
|
|
| `top` | number | 위쪽 가장자리로부터의 Y 오프셋 |
|
|
| `width` | number | 자르기 영역의 너비 |
|
|
| `height` | number | 자르기 영역의 높이 |
|
|
| `unit` | string | `px`(기본값) 또는 `percent` |
|
|
|
|
### rotate {#rotate}
|
|
|
|
이미지를 지정한 각도만큼 회전합니다.
|
|
|
|
| 매개변수 | 타입 | 설명 |
|
|
|---|---|---|
|
|
| `angle` | number | 회전 각도(도 단위, 0-360) |
|
|
| `background` | string | 노출된 영역의 채우기 색상(기본값: `#000000`). 90도가 아닌 각도에만 적용됩니다. |
|
|
|
|
### flip {#flip}
|
|
|
|
이미지를 수평, 수직 또는 둘 다 반전합니다. 최소한 하나는 true여야 합니다.
|
|
|
|
| 매개변수 | 타입 | 설명 |
|
|
|---|---|---|
|
|
| `horizontal` | boolean | 좌우 반전 |
|
|
| `vertical` | boolean | 상하 반전 |
|
|
|
|
### convert {#convert}
|
|
|
|
이미지 형식을 변경합니다.
|
|
|
|
| 매개변수 | 타입 | 설명 |
|
|
|---|---|---|
|
|
| `format` | string | 목표 형식: `jpg`, `png`, `webp`, `avif`, `tiff`, `gif`, `jxl`, `heic`, `heif`, `bmp`, `ico`, `jp2`, `qoi` |
|
|
| `quality` | number | 압축 품질(1-100, 손실 형식에 적용) |
|
|
|
|
처음 일곱 개 형식(`jpg`부터 `jxl`까지)은 Sharp에 의해 프로세스 내에서 인코딩됩니다. 나머지 형식은 API 계층에서 외부 인코더를 사용합니다: `heic`/`heif`는 heif-enc를 통해, `bmp`/`ico`는 ImageMagick을 통해, `jp2`는 opj_compress를 통해, `qoi`는 인라인 TypeScript 코덱을 통해 처리됩니다.
|
|
|
|
### compress {#compress}
|
|
|
|
형식은 그대로 유지하면서 파일 크기를 줄입니다.
|
|
|
|
| 매개변수 | 타입 | 설명 |
|
|
|---|---|---|
|
|
| `quality` | number | 목표 품질(1-100) |
|
|
| `targetSizeBytes` | number | 선택적 목표 파일 크기(바이트) |
|
|
| `format` | string | 선택적 형식 재정의 |
|
|
|
|
### strip-metadata {#strip-metadata}
|
|
|
|
이미지에서 EXIF, IPTC, XMP, ICC 메타데이터를 제거합니다. 매개변수가 없으면(또는 `stripAll: true`) 모든 것을 제거합니다. 선택적 제거를 위해 개별 플래그를 전달하세요.
|
|
|
|
| 매개변수 | 타입 | 설명 |
|
|
|---|---|---|
|
|
| `stripAll` | boolean | 모든 메타데이터 제거(플래그가 설정되지 않았을 때 기본값) |
|
|
| `stripExif` | boolean | EXIF 데이터 제거(`stripGps`가 별도로 설정되지 않은 경우 GPS 포함) |
|
|
| `stripGps` | boolean | GPS 위치 데이터 제거 |
|
|
| `stripIcc` | boolean | ICC 색상 프로파일 제거 |
|
|
| `stripXmp` | boolean | XMP 메타데이터 제거 |
|
|
|
|
### 색상 조정 {#color-adjustments}
|
|
|
|
이 작업들은 이미지의 색상 속성을 수정합니다. 각각 하나의 숫자 값을 받습니다.
|
|
|
|
| 작업 | 매개변수 | 범위 | 설명 |
|
|
|---|---|---|---|
|
|
| `brightness` | `value` | -100 ~ 100 | 밝기 조정 |
|
|
| `contrast` | `value` | -100 ~ 100 | 대비 조정 |
|
|
| `saturation` | `value` | -100 ~ 100 | 색상 채도 조정 |
|
|
|
|
### 색상 필터 {#color-filters}
|
|
|
|
이 필터들은 고정된 색상 변환을 적용합니다. 매개변수를 받지 않습니다.
|
|
|
|
| 작업 | 설명 |
|
|
|---|---|
|
|
| `grayscale` | 회색조로 변환 |
|
|
| `sepia` | 세피아 톤 적용 |
|
|
| `invert` | 모든 색상 반전 |
|
|
|
|
### 색상 채널 {#color-channels}
|
|
|
|
개별 RGB 색상 채널을 조정합니다. 값은 100 = 변화 없음인 배율입니다.
|
|
|
|
| 매개변수 | 타입 | 설명 |
|
|
|---|---|---|
|
|
| `red` | number | 적색 채널 배율(0 ~ 200, 100 = 변화 없음) |
|
|
| `green` | number | 녹색 채널 배율(0 ~ 200, 100 = 변화 없음) |
|
|
| `blue` | number | 청색 채널 배율(0 ~ 200, 100 = 변화 없음) |
|
|
|
|
### sharpen {#sharpen}
|
|
|
|
단일 값으로 제어되는 간단한 선명화입니다.
|
|
|
|
| 매개변수 | 타입 | 설명 |
|
|
|---|---|---|
|
|
| `value` | number | 선명화 강도(0 ~ 100). 0.5-10의 가우시안 시그마로 매핑됩니다. |
|
|
|
|
### sharpen-advanced {#sharpen-advanced}
|
|
|
|
선택 가능한 세 가지 방식과 선택적 노이즈 감소 사전 패스를 갖춘 고급 선명화입니다.
|
|
|
|
| 매개변수 | 타입 | 설명 |
|
|
|---|---|---|
|
|
| `method` | string | `adaptive`, `unsharp-mask`, 또는 `high-pass` |
|
|
| `sigma` | number | 가우시안 블러 반경, 0.5-10(적응형) |
|
|
| `m1` | number | 평탄 영역 선명화, 0-10(적응형) |
|
|
| `m2` | number | 텍스처 영역 선명화, 0-20(적응형) |
|
|
| `x1` | number | 평탄/거친 영역 임계값, 0-10(적응형) |
|
|
| `y2` | number | 최대 밝게 하기(헤일로 클램프), 0-50(적응형) |
|
|
| `y3` | number | 최대 어둡게 하기(헤일로 클램프), 0-50(적응형) |
|
|
| `amount` | number | 강도 백분율, 0-500(언샤프 마스크) |
|
|
| `radius` | number | 블러 반경, 0.1-5.0(언샤프 마스크) |
|
|
| `threshold` | number | 최소 가장자리 밝기, 0-255(언샤프 마스크) |
|
|
| `strength` | number | 블렌드 강도, 0-100(하이패스) |
|
|
| `kernelSize` | number | 3x3 / 5x5 커널에 대해 `3` 또는 `5`(하이패스) |
|
|
| `denoise` | string | 노이즈 감소 사전 패스: `off`, `light`, `medium`, 또는 `strong` |
|
|
|
|
매개변수는 방식별로 다릅니다. 선택한 방식에 관련된 것만 제공하세요.
|
|
|
|
### color-blindness {#color-blindness}
|
|
|
|
3x3 색상 재조합 행렬을 사용해 색각 이상을 시뮬레이션합니다.
|
|
|
|
| 매개변수 | 타입 | 설명 |
|
|
|---|---|---|
|
|
| `type` | string | 다음 중 하나: `protanopia`, `deuteranopia`, `tritanopia`, `protanomaly`, `deuteranomaly`, `tritanomaly`, `achromatopsia`, `blueConeMonochromacy` |
|
|
|
|
### edit-metadata {#edit-metadata}
|
|
|
|
전체 블록을 제거하지 않고 개별 EXIF/IPTC 메타데이터 필드를 작성하거나 제거합니다.
|
|
|
|
| 매개변수 | 타입 | 설명 |
|
|
|---|---|---|
|
|
| `artist` | string | EXIF Artist 태그 |
|
|
| `copyright` | string | EXIF Copyright 태그 |
|
|
| `imageDescription` | string | EXIF ImageDescription 태그 |
|
|
| `software` | string | EXIF Software 태그 |
|
|
| `dateTime` | string | EXIF DateTime 태그 |
|
|
| `dateTimeOriginal` | string | EXIF DateTimeOriginal 태그 |
|
|
| `clearGps` | boolean | 모든 GPS 태그 제거 |
|
|
| `fieldsToRemove` | string[] | 삭제할 EXIF 필드명 목록 |
|
|
|
|
모든 매개변수는 선택 사항입니다. `fieldsToRemove`에 나열된 필드는 기존 EXIF 블록에서 삭제됩니다. 명명된 매개변수를 통해 설정된 필드는 기록(또는 덮어쓰기)됩니다. MakerNote 같은 바이너리/안전하지 않은 키는 조용히 무시됩니다.
|
|
|
|
## 형식 감지 {#format-detection}
|
|
|
|
엔진은 파일 확장자뿐 아니라 파일 헤더로부터 입력 형식을 자동으로 감지합니다. 따라서 실제로는 PNG인 `.jpg` 파일도 올바르게 처리됩니다. 감지는 다층 방식을 사용합니다: 먼저 매직 바이트, 그다음 대체 수단으로 파일 확장자를 사용합니다.
|
|
|
|
SnapOtter는 **55개 이상의 입력 형식**과 **13개의 출력 형식**을 지원하며, 여기에는 20개 이상 브랜드의 카메라 RAW 형식 23종, 전문 형식(PSD, EPS, OpenEXR, HDR), 최신 코덱(JPEG XL, AVIF, HEIC, QOI, JPEG 2000), 과학/게임 형식(FITS, DDS)이 포함됩니다. 디코딩은 가능한 경우 Sharp가 기본적으로 처리하며, ImageMagick, LibRaw, 특수 CLI 디코더로 자동 대체됩니다.
|
|
|
|
전체 목록은 [지원 형식](/ko/guide/supported-formats) 페이지를 참고하세요.
|
|
|
|
## 메타데이터 추출 {#metadata-extraction}
|
|
|
|
`info` 도구는 이미지 메타데이터를 반환합니다. 전체 필드 레퍼런스는 [이미지 정보](/ko/tools/image/info)를 참고하세요.
|
|
|
|
```json
|
|
{
|
|
"filename": "photo.jpg",
|
|
"fileSize": 2450000,
|
|
"width": 4032,
|
|
"height": 3024,
|
|
"format": "jpeg",
|
|
"channels": 3,
|
|
"hasAlpha": false,
|
|
"colorSpace": "srgb",
|
|
"density": 72,
|
|
"isProgressive": false,
|
|
"hasExif": true,
|
|
"hasIcc": true,
|
|
"hasXmp": false,
|
|
"bitDepth": "8",
|
|
"pages": 1,
|
|
"histogram": [
|
|
{ "channel": "red", "min": 0, "max": 255, "mean": 128.45, "stdev": 52.31 },
|
|
{ "channel": "green", "min": 2, "max": 253, "mean": 115.22, "stdev": 48.76 },
|
|
{ "channel": "blue", "min": 0, "max": 250, "mean": 102.89, "stdev": 55.14 }
|
|
]
|
|
}
|
|
```
|