Riferimento API

Sharp fornisce API ricche per elaborare immagini. Questa pagina fornisce riferimenti dettagliati per tutti i metodi disponibili.

Costruttore

sharp(input, options?)

Crea una nuova istanza Sharp.

import sharp from 'sharp';

// Creare da file
const image = sharp('input.jpg');

// Creare da Buffer
const image = sharp(buffer);

// Creare da Stream
const image = sharp(stream);

// Creare immagine vuota
const image = sharp({
  create: {
    width: 300,
    height: 200,
    channels: 4,
    background: { r: 255, g: 0, b: 0, alpha: 1 }
  }
});

Metadati input

metadata()

Ottiene informazioni metadati dell'immagine.

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()

Ottiene statistiche dell'immagine.

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

Opzioni output

toFile(filename, callback?)

Salva l'immagine elaborata su file.

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

toBuffer(options?, callback?)

Output dell'immagine elaborata come Buffer.

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

toFormat(format, options?)

Imposta formato output.

// 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');

Regolazione immagine

resize(width?, height?, options?)

Ridimensiona l'immagine.

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

// Mantenere proporzioni
await sharp('input.jpg')
  .resize(300, null)
  .toFile('output.jpg');

// Usare modalità adattamento
await sharp('input.jpg')
  .resize(300, 200, {
    fit: 'cover',        // Ritagliare per adattarsi
    position: 'center',  // Ritaglio centrato
    background: { r: 255, g: 255, b: 255, alpha: 1 }
  })
  .toFile('output.jpg');

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

extract(region)

Ritaglia area immagine.

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

trim(threshold?)

Ritaglia automaticamente bordi trasparenti o bianchi.

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

Operazioni immagine

rotate(angle, options?)

Ruota l'immagine.

// Ruotare 90 gradi
await sharp('input.jpg')
  .rotate(90)
  .toFile('rotated.jpg');

// Ruotare e riempire sfondo
await sharp('input.jpg')
  .rotate(45, { background: { r: 255, g: 255, b: 255, alpha: 1 } })
  .toFile('rotated.jpg');

flip(flip?)

Capovolge verticalmente l'immagine.

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

flop(flop?)

Capovolge orizzontalmente l'immagine.

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

affine(matrix, options?)

Applica trasformazione affine.

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

Effetti filtro

blur(sigma?)

Applica sfocatura gaussiana.

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

sharpen(sigma?, flat?, jagged?)

Applica filtro nitidezza.

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

// Parametri nitidezza personalizzati
await sharp('input.jpg')
  .sharpen(1, 1, 2)
  .toFile('sharpened.jpg');

median(size?)

Applica filtro mediano.

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

flatten(options?)

Unisce canale trasparenza.

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

Operazioni colore

grayscale(grayscale?)

Converte in immagine scala di grigi.

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

negate(negate?)

Effetto negativo.

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

modulate(options?)

Regola luminosità, saturazione e tonalità.

await sharp('input.jpg')
  .modulate({
    brightness: 1.2,    // Luminosità
    saturation: 0.8,    // Saturazione
    hue: 90             // Tonalità
  })
  .toFile('modulated.jpg');

tint(rgb)

Applica tinta.

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

removeAlpha()

Rimuove canale trasparenza.

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

ensureAlpha()

Assicura presenza canale trasparenza.

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

Operazioni canali

bandbool(boolean)

Applica operazione booleana ai canali.

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

joinChannel(channels)

Unisce canali.

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

extractChannel(channel)

Estrae singolo canale.

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

Proprietà globali

sharp.versions

Ottiene informazioni versione.

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

sharp.format

Ottiene formati supportati.

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

sharp.kernel

Ottiene kernel disponibili.

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

Gestione errori

try {
  await sharp('input.jpg')
    .resize(300, 200)
    .toFile('output.jpg');
} catch (error) {
  console.error('Elaborazione immagine fallita:', error);
}

Ottimizzazione prestazioni

Elaborazione streaming

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

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

Elaborazione concorrente

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

const results = await Promise.all(promises);

Esempio completo

import sharp from 'sharp';

async function processImage() {
  try {
    // Ottenere metadati
    const metadata = await sharp('input.jpg').metadata();
    console.log('Dimensioni immagine originale:', metadata.width, 'x', metadata.height);

    // Creare più versioni
    const promises = [
      // Miniatura
      sharp('input.jpg')
        .resize(150, 150, { fit: 'cover' })
        .jpeg({ quality: 90 })
        .toFile('thumbnail.jpg'),

      // Dimensione media
      sharp('input.jpg')
        .resize(800, 600, { fit: 'inside' })
        .webp({ quality: 80 })
        .toFile('medium.webp'),

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

      // Versione scala di grigi
      sharp('input.jpg')
        .grayscale()
        .jpeg({ quality: 80 })
        .toFile('grayscale.jpg')
    ];

    await Promise.all(promises);
    console.log('Tutte le immagini elaborate completate!');
  } catch (error) {
    console.error('Elaborazione fallita:', error);
  }
}

processImage();

Prossimi passi

• Consultare la pagina esempi per maggiori utilizzi
• Comprendere tecniche di ottimizzazione prestazioni
• Consultare il changelog per conoscere le ultime funzionalità