API 참조

Sharp는 이미지를 처리하기 위한 풍부한 API를 제공합니다. 이 페이지는 사용 가능한 모든 메서드에 대한 상세한 참조를 제공합니다.

생성자

sharp(input, options?)

새로운 Sharp 인스턴스를 생성합니다.

javascript

import sharp from 'sharp';

// 파일에서 생성
const image = sharp('input.jpg');

// Buffer에서 생성
const image = sharp(buffer);

// Stream에서 생성
const image = sharp(stream);

// 빈 이미지 생성
const image = sharp({
  create: {
    width: 300,
    height: 200,
    channels: 4,
    background: { r: 255, g: 0, b: 0, alpha: 1 }
  }
});

입력 메타데이터

metadata()

이미지의 메타데이터 정보를 가져옵니다.

javascript

const metadata = await sharp('input.jpg').metadata();
console.log(metadata);
// {
//   format: 'jpeg',
//   width: 1920,
//   height: 1080,
//   space: 'srgb',
//   channels: 3,
//   depth: 'uchar',
//   density: 72,
//   hasProfile: false,
//   hasAlpha: false
// }

stats()

이미지의 통계 정보를 가져옵니다.

javascript

const stats = await sharp('input.jpg').stats();
console.log(stats);
// {
//   isOpaque: true,
//   dominant: { r: 128, g: 128, b: 128 }
// }

출력 옵션

toFile(filename, callback?)

처리된 이미지를 파일로 저장합니다.

javascript

await sharp('input.jpg')
  .resize(300, 200)
  .toFile('output.jpg');

toBuffer(options?, callback?)

처리된 이미지를 Buffer로 출력합니다.

javascript

const buffer = await sharp('input.jpg')
  .resize(300, 200)
  .jpeg()
  .toBuffer();

toFormat(format, options?)

출력 형식을 설정합니다.

javascript

// JPEG
await sharp('input.png')
  .jpeg({ quality: 80, progressive: true })
  .toFile('output.jpg');

// PNG
await sharp('input.jpg')
  .png({ compressionLevel: 9, adaptiveFiltering: true })
  .toFile('output.png');

// WebP
await sharp('input.jpg')
  .webp({ quality: 80, effort: 6 })
  .toFile('output.webp');

// AVIF
await sharp('input.jpg')
  .avif({ quality: 80, effort: 4 })
  .toFile('output.avif');

// TIFF
await sharp('input.jpg')
  .tiff({ quality: 80, compression: 'lzw' })
  .toFile('output.tiff');

이미지 크기 조정

resize(width?, height?, options?)

이미지 크기를 조정합니다.

javascript

// 기본 크기 조정
await sharp('input.jpg')
  .resize(300, 200)
  .toFile('output.jpg');

// 종횡비 유지
await sharp('input.jpg')
  .resize(300, null)
  .toFile('output.jpg');

// 적합 모드 사용
await sharp('input.jpg')
  .resize(300, 200, {
    fit: 'cover',        // 잘라서 맞추기
    position: 'center',  // 중앙 자르기
    background: { r: 255, g: 255, b: 255, alpha: 1 }
  })
  .toFile('output.jpg');

// 커널 사용
await sharp('input.jpg')
  .resize(300, 200, {
    kernel: sharp.kernel.lanczos3
  })
  .toFile('output.jpg');

extract(region)

이미지 영역을 자릅니다.

javascript

await sharp('input.jpg')
  .extract({ left: 100, top: 100, width: 200, height: 200 })
  .toFile('cropped.jpg');

trim(threshold?)

투명하거나 흰색 가장자리를 자동으로 자릅니다.

javascript

await sharp('input.png')
  .trim()
  .toFile('trimmed.png');

이미지 작업

rotate(angle, options?)

이미지를 회전합니다.

javascript

// 90도 회전
await sharp('input.jpg')
  .rotate(90)
  .toFile('rotated.jpg');

// 회전 및 배경 채우기
await sharp('input.jpg')
  .rotate(45, { background: { r: 255, g: 255, b: 255, alpha: 1 } })
  .toFile('rotated.jpg');

flip(flip?)

이미지를 수직으로 뒤집습니다.

javascript

await sharp('input.jpg')
  .flip()
  .toFile('flipped.jpg');

flop(flop?)

이미지를 수평으로 뒤집습니다.

javascript

await sharp('input.jpg')
  .flop()
  .toFile('flopped.jpg');

affine(matrix, options?)

아핀 변환을 적용합니다.

javascript

await sharp('input.jpg')
  .affine([[1, 0.3], [0, 1]], { background: { r: 255, g: 255, b: 255, alpha: 1 } })
  .toFile('transformed.jpg');

필터 효과

blur(sigma?)

가우시안 블러를 적용합니다.

javascript

await sharp('input.jpg')
  .blur(5)
  .toFile('blurred.jpg');

sharpen(sigma?, flat?, jagged?)

선명화 필터를 적용합니다.

javascript

await sharp('input.jpg')
  .sharpen()
  .toFile('sharpened.jpg');

// 사용자 정의 선명화 매개변수
await sharp('input.jpg')
  .sharpen(1, 1, 2)
  .toFile('sharpened.jpg');

median(size?)

중간값 필터를 적용합니다.

javascript

await sharp('input.jpg')
  .median(3)
  .toFile('median.jpg');

flatten(options?)

투명 채널을 병합합니다.

javascript

await sharp('input.png')
  .flatten({ background: { r: 255, g: 255, b: 255 } })
  .toFile('flattened.jpg');

색상 작업

grayscale(grayscale?)

그레이스케일 이미지로 변환합니다.

javascript

await sharp('input.jpg')
  .grayscale()
  .toFile('grayscale.jpg');

negate(negate?)

네거티브 효과를 적용합니다.

javascript

await sharp('input.jpg')
  .negate()
  .toFile('negated.jpg');

modulate(options?)

밝기, 채도 및 색조를 조정합니다.

javascript

await sharp('input.jpg')
  .modulate({
    brightness: 1.2,    // 밝기
    saturation: 0.8,    // 채도
    hue: 90             // 색조
  })
  .toFile('modulated.jpg');

tint(rgb)

색조를 적용합니다.

javascript

await sharp('input.jpg')
  .tint({ r: 255, g: 0, b: 0 })
  .toFile('tinted.jpg');

removeAlpha()

투명 채널을 제거합니다.

javascript

await sharp('input.png')
  .removeAlpha()
  .toFile('no-alpha.jpg');

ensureAlpha()

투명 채널이 있는지 확인합니다.

javascript

await sharp('input.jpg')
  .ensureAlpha()
  .toFile('with-alpha.png');

채널 작업

bandbool(boolean)

채널에 부울 연산을 적용합니다.

javascript

await sharp('input.jpg')
  .bandbool('and')
  .toFile('bandbool.jpg');

joinChannel(channels)

채널을 병합합니다.

javascript

await sharp('input.jpg')
  .joinChannel(['red.jpg', 'green.jpg', 'blue.jpg'])
  .toFile('joined.jpg');

extractChannel(channel)

단일 채널을 추출합니다.

javascript

await sharp('input.jpg')
  .extractChannel('red')
  .toFile('red-channel.jpg');

전역 속성

sharp.versions

버전 정보를 가져옵니다.

javascript

console.log(sharp.versions);
// {
//   sharp: '0.32.0',
//   vips: '8.14.0'
// }

sharp.format

지원되는 형식을 가져옵니다.

javascript

console.log(sharp.format);
// {
//   jpeg: { id: 'jpeg', ... },
//   png: { id: 'png', ... },
//   webp: { id: 'webp', ... },
//   ...
// }

sharp.kernel

사용 가능한 커널을 가져옵니다.

javascript

console.log(sharp.kernel);
// {
//   nearest: 'nearest',
//   cubic: 'cubic',
//   mitchell: 'mitchell',
//   lanczos2: 'lanczos2',
//   lanczos3: 'lanczos3'
// }

오류 처리

javascript

try {
  await sharp('input.jpg')
    .resize(300, 200)
    .toFile('output.jpg');
} catch (error) {
  console.error('이미지 처리 실패:', error);
}

성능 최적화

스트림 처리

javascript

const pipeline = sharp()
  .resize(300, 200)
  .jpeg({ quality: 80 });

fs.createReadStream('large-input.jpg')
  .pipe(pipeline)
  .pipe(fs.createWriteStream('output.jpg'));

동시 처리

javascript

const promises = images.map(image => 
  sharp(image)
    .resize(300, 200)
    .jpeg()
    .toBuffer()
);

const results = await Promise.all(promises);

전체 예제

javascript

import sharp from 'sharp';

async function processImage() {
  try {
    // 메타데이터 가져오기
    const metadata = await sharp('input.jpg').metadata();
    console.log('원본 이미지 크기:', metadata.width, 'x', metadata.height);

    // 여러 버전 생성
    const promises = [
      // 썸네일
      sharp('input.jpg')
        .resize(150, 150, { fit: 'cover' })
        .jpeg({ quality: 90 })
        .toFile('thumbnail.jpg'),

      // 중간 크기
      sharp('input.jpg')
        .resize(800, 600, { fit: 'inside' })
        .webp({ quality: 80 })
        .toFile('medium.webp'),

      // 대용량
      sharp('input.jpg')
        .resize(1920, 1080, { fit: 'inside' })
        .jpeg({ quality: 85, progressive: true })
        .toFile('large.jpg'),

      // 그레이스케일 버전
      sharp('input.jpg')
        .grayscale()
        .jpeg({ quality: 80 })
        .toFile('grayscale.jpg')
    ];

    await Promise.all(promises);
    console.log('모든 이미지 처리 완료!');
  } catch (error) {
    console.error('처리 실패:', error);
  }
}

processImage();

다음 단계

예제 페이지를 확인하여 더 많은 사용법 알아보기
성능 최적화 기술 알아보기
변경 로그를 확인하여 최신 기능 알아보기

API 참조 ​

생성자 ​

sharp(input, options?) ​

입력 메타데이터 ​

metadata() ​

stats() ​

출력 옵션 ​

toFile(filename, callback?) ​

toBuffer(options?, callback?) ​

toFormat(format, options?) ​

이미지 크기 조정 ​

resize(width?, height?, options?) ​

extract(region) ​

trim(threshold?) ​

이미지 작업 ​

rotate(angle, options?) ​

flip(flip?) ​

flop(flop?) ​

affine(matrix, options?) ​

필터 효과 ​

blur(sigma?) ​

sharpen(sigma?, flat?, jagged?) ​

median(size?) ​

flatten(options?) ​

색상 작업 ​

grayscale(grayscale?) ​

negate(negate?) ​

modulate(options?) ​

tint(rgb) ​

removeAlpha() ​

ensureAlpha() ​

채널 작업 ​

bandbool(boolean) ​

joinChannel(channels) ​

extractChannel(channel) ​

전역 속성 ​

sharp.versions ​

sharp.format ​

sharp.kernel ​

오류 처리 ​

성능 최적화 ​

스트림 처리 ​

동시 처리 ​

전체 예제 ​

다음 단계 ​

API 참조

생성자

sharp(input, options?)

입력 메타데이터

metadata()

stats()

출력 옵션

toFile(filename, callback?)

toBuffer(options?, callback?)

toFormat(format, options?)

이미지 크기 조정

resize(width?, height?, options?)

extract(region)

trim(threshold?)

이미지 작업

rotate(angle, options?)

flip(flip?)

flop(flop?)

affine(matrix, options?)

필터 효과

blur(sigma?)

sharpen(sigma?, flat?, jagged?)

median(size?)

flatten(options?)

색상 작업

grayscale(grayscale?)

negate(negate?)

modulate(options?)

tint(rgb)

removeAlpha()

ensureAlpha()

채널 작업

bandbool(boolean)

joinChannel(channels)

extractChannel(channel)

전역 속성

sharp.versions

sharp.format

sharp.kernel

오류 처리

성능 최적화

스트림 처리

동시 처리

전체 예제

다음 단계