34.2 Images

Images go in as bytes (PNG, JPEG or WebP) and come back as PNG:

byte[] photo = await db.FileDownloadAsync(venue, v => v.Photo);

// what the image shows, in Norwegian
var meta = await db.Services.Imaging.ImageToMetaAsync(photo, "nb");
string title = meta.Title;              // "Fullsatt konsertsal"
string[] keywords = meta.Keywords;      // ["konsert", "publikum", "scene", ...]

// change the image and store the result
var cutout = await db.Services.Imaging.RemoveBackgroundAsync(photo);
var larger = await db.Services.Imaging.UpscaleAsync(cutout.Png, 2);
await db.FileUploadAsync(venue, v => v.Photo, larger.Png, "venue.png");

Method	What it returns
`CreateImageAsync(description, inspiration?, width?, height?, transparent?)`	A new image from a description, optionally in the style of other images
`ManipulateImageAsync(image, instruction, references?, mask?)`	The image changed as instructed ("make it winter"); with a mask, only where it is white
`RemoveBackgroundAsync(image)`	The subject on a transparent background
`UpscaleAsync(image, factor)`	The image 2 or 4 times larger each way, with added detail
`RemoveObjectAsync(image, mask)`	The image without what the mask covers, filled in to match
`ExpandImageAsync(image, margins, hint?)`	The image on a larger canvas, with the new space filled in
`ShrinkImageAsync(image, margins)`	The image on a smaller canvas, with the subject kept whole
`RotateIfNeededAsync(image)`	The image turned upright if it is upside down or on its side (below)
`ImageToMetaAsync(image, language?)`	A title, a description and keywords, a focus point, and the objects in the image
`AskAboutImageAsync(image, question)`	An answer in words (below)
`AskAboutImageBoolAsync(image, question)`	Yes or no, with a certainty from 0 to 100
`GetOperationsAsync()`	The operations offered, their price and the largest file allowed. Free

An image answer is an ImagingImage: the Png, its Width, Height and Sha256, and the price fields of §34.5.

A mask has the image's size. White or opaque marks what to change; black or transparent marks what to keep.
Margins are pixels per side: new ImageMargins(Top: 100, Left: 50) or ImageMargins.All(64).
Focus is the point to keep when you crop the image, such as the main face. Not every provider finds it, so Focus can be null and Objects empty.
Chained calls upload nothing again. The service keeps each image it receives or makes, by its SHA-256, so passing cutout.Png on sends only its hash.
Text in an image is read by db.Services.FileToText. ImageToMetaAsync leaves the words out.

Turning an image the right way up

var turn = await db.Services.Imaging.RotateIfNeededAsync(photo);
if (turn.Rotated) await db.FileUploadAsync(venue, v => v.Photo, turn.Image!.Png, "photo.png");

The service looks at what the image shows (people standing, sky at the top, text the right way) and turns it clockwise by Rotation: 90, 180 or 270 degrees. When the image is upright already, or up cannot be told, Rotation is 0 and Image is null. The call costs the same either way. Exif orientation is applied already; this is for images whose pixels are the wrong way round.

Asking about an image

var sign = await db.Services.Imaging.AskAboutImageAsync(photo, "Hva står det på skiltet over døra?");
Console.WriteLine(sign.Answer);   // in the language of the question

var dog = await db.Services.Imaging.AskAboutImageBoolAsync(photo, "Is there a dog in the picture?");
bool surelyADog = dog.Answer && dog.Certainty >= 80;

AskAboutImageAsync answers briefly, and says so when the image does not show what you asked about. AskAboutImageBoolAsync gives Answer and Certainty, from 0 (a guess) to 100 (plainly shown). Decide on both: a false at 20 says little, while a false at 95 means the image shows it is not so.