유틸리티 API
Sharp는 이미지 처리 및 형식 변환을 보조하는 다양한 유틸리티 함수를 제공합니다.
형식 감지
지원되는 형식 확인
javascript
import sharp from 'sharp';
// 지원되는 입력 형식 가져오기
console.log('지원되는 입력 형식:', sharp.format);
// 지원되는 출력 형식 가져오기
console.log('지원되는 출력 형식:', sharp.format);파일 형식 확인
javascript
async function checkImageFormat(filePath) {
try {
const metadata = await sharp(filePath).metadata();
return {
format: metadata.format,
width: metadata.width,
height: metadata.height,
channels: metadata.channels
};
} catch (error) {
return { error: error.message };
}
}색상 공간
색상 공간 상수
javascript
// 사용 가능한 색상 공간
sharp.colourspace.srgb // sRGB
sharp.colourspace.rgb // RGB
sharp.colourspace.cmyk // CMYK
sharp.colourspace.grey // 그레이스케일
sharp.colourspace.multiband // 다중 밴드
sharp.colourspace.lab // Lab
sharp.colourspace.xyz // XYZ
sharp.colourspace.ycbcr // YCbCr색상 공간 변환
javascript
// 그레이스케일로 변환
sharp('input.jpg')
.grayscale()
.toFile('output.jpg');
// CMYK로 변환
sharp('input.jpg')
.toColourspace(sharp.colourspace.cmyk)
.tiff()
.toFile('output.tiff');커널 및 필터
크기 조정 커널
javascript
// 사용 가능한 크기 조정 커널
sharp.kernel.nearest // 최근접 이웃
sharp.kernel.cubic // 3차 보간
sharp.kernel.mitchell // Mitchell-Netravali
sharp.kernel.lanczos2 // Lanczos 2-lobed
sharp.kernel.lanczos3 // Lanczos 3-lobed (기본값)사용자 정의 커널 사용
javascript
// 사용자 정의 크기 조정 커널 사용
sharp('input.jpg')
.resize(300, 200, { kernel: sharp.kernel.lanczos3 })
.toFile('output.jpg');위치 상수
위치 옵션
javascript
// 사용 가능한 위치 옵션
sharp.position.top // 상단
sharp.position.right // 오른쪽
sharp.position.bottom // 하단
sharp.position.left // 왼쪽
sharp.position.center // 중앙 (기본값)
sharp.position.centre // 중앙 (영국식 철자)
sharp.position.north // 북 (상단)
sharp.position.east // 동 (오른쪽)
sharp.position.south // 남 (하단)
sharp.position.west // 서 (왼쪽)
sharp.position.northeast // 북동
sharp.position.southeast // 남동
sharp.position.southwest // 남서
sharp.position.northwest // 북서채널 작업
채널 상수
javascript
// 채널 상수
sharp.channel.red // 빨간색 채널
sharp.channel.green // 녹색 채널
sharp.channel.blue // 파란색 채널
sharp.channel.alpha // 투명도 채널
sharp.channel.grey // 그레이스케일 채널채널 작업
javascript
// 빨간색 채널 추출
sharp('input.jpg')
.extractChannel(sharp.channel.red)
.toFile('red-channel.jpg');
// 모든 채널 추출
const channels = await sharp('input.jpg').separate();오류 처리
오류 유형
javascript
// 일반적인 Sharp 오류
sharp.errors.InputError // 입력 오류
sharp.errors.ProcessError // 처리 오류
sharp.errors.OutputError // 출력 오류오류 처리 예제
javascript
try {
await sharp('input.jpg')
.resize(300, 200)
.toFile('output.jpg');
} catch (error) {
if (error instanceof sharp.errors.InputError) {
console.error('입력 파일 오류:', error.message);
} else if (error instanceof sharp.errors.ProcessError) {
console.error('처리 오류:', error.message);
} else if (error instanceof sharp.errors.OutputError) {
console.error('출력 오류:', error.message);
} else {
console.error('알 수 없는 오류:', error.message);
}
}성능 모니터링
메모리 사용
javascript
// Sharp 메모리 사용량 가져오기
const stats = sharp.cache();
console.log('캐시 통계:', stats);
// 캐시 지우기
sharp.cache(false);동시성 제어
javascript
// 동시성 제한 설정
sharp.concurrency(4); // 최대 4개의 동시 작업
// 현재 동시성 수 가져오기
console.log('현재 동시성 수:', sharp.concurrency());도구 함수
테스트 이미지 생성
javascript
// 단색 이미지 생성
const redImage = sharp({
create: {
width: 300,
height: 200,
channels: 3,
background: { r: 255, g: 0, b: 0 }
}
});
// 그라데이션 이미지 생성
const gradient = sharp({
create: {
width: 300,
height: 200,
channels: 3,
background: { r: 0, g: 0, b: 0 }
}
});이미지 합성
javascript
// 여러 이미지 합성
const composite = await sharp('background.jpg')
.composite([
{
input: 'overlay.png',
top: 100,
left: 100
}
])
.jpeg()
.toBuffer();일괄 처리 도구
일괄 크기 조정
javascript
const fs = require('fs').promises;
async function batchResize(inputDir, outputDir, width, height) {
const files = await fs.readdir(inputDir);
for (const file of files) {
if (file.match(/\.(jpg|jpeg|png|webp)$/i)) {
try {
await sharp(`${inputDir}/${file}`)
.resize(width, height)
.jpeg({ quality: 80 })
.toFile(`${outputDir}/${file}`);
console.log(`처리 완료: ${file}`);
} catch (error) {
console.error(`처리 실패 ${file}:`, error.message);
}
}
}
}일괄 형식 변환
javascript
async function batchConvert(inputDir, outputDir, format) {
const files = await fs.readdir(inputDir);
for (const file of files) {
if (file.match(/\.(jpg|jpeg|png|webp)$/i)) {
const outputFile = file.replace(/\.[^.]+$/, `.${format}`);
try {
const image = sharp(`${inputDir}/${file}`);
switch (format) {
case 'jpg':
case 'jpeg':
await image.jpeg({ quality: 80 }).toFile(`${outputDir}/${outputFile}`);
break;
case 'png':
await image.png().toFile(`${outputDir}/${outputFile}`);
break;
case 'webp':
await image.webp({ quality: 80 }).toFile(`${outputDir}/${outputFile}`);
break;
case 'avif':
await image.avif({ quality: 80 }).toFile(`${outputDir}/${outputFile}`);
break;
}
console.log(`변환 완료: ${file} -> ${outputFile}`);
} catch (error) {
console.error(`변환 실패 ${file}:`, error.message);
}
}
}
}검증 도구
이미지 무결성 검증
javascript
async function validateImage(filePath) {
try {
const metadata = await sharp(filePath).metadata();
// 기본 속성 확인
if (!metadata.width || !metadata.height) {
return { valid: false, error: '크기 정보 누락' };
}
if (metadata.width <= 0 || metadata.height <= 0) {
return { valid: false, error: '유효하지 않은 크기' };
}
if (!metadata.format) {
return { valid: false, error: '형식 정보 누락' };
}
// 이미지 처리 시도
await sharp(filePath).resize(1, 1).toBuffer();
return { valid: true, metadata };
} catch (error) {
return { valid: false, error: error.message };
}
}파일 크기 확인
javascript
const fs = require('fs');
function checkFileSize(filePath, maxSize = 10 * 1024 * 1024) { // 10MB
const stats = fs.statSync(filePath);
const sizeInMB = stats.size / (1024 * 1024);
return {
size: stats.size,
sizeInMB,
isValid: stats.size <= maxSize,
maxSizeInMB: maxSize / (1024 * 1024)
};
}