Une image posée dans un rectangle

En mots de tous les jours

Écrit pour tout le monde. Il dit ce que cela pose sur une feuille de papier, et ne vous demande rien de plus.

Vous envoyez votre photo ou votre logo en même temps que votre demande, et vous dites à quel endroit de la feuille il doit apparaître. Vous donnez un cadre, et l'image vient s'y installer. Vous choisissez entre deux façons : soit elle remplit tout le cadre, soit elle garde sa forme d'origine et se centre dans ce qui reste, sans être déformée. La même image peut servir à plusieurs endroits, en petit dans un coin et en grand sur une autre page, sans être envoyée deux fois.

Pour un développeur

Écrit pour celui qui écrit le programme appelant : le modèle, les unités, et les réglages qui portent le poids.

Les octets de l'image voyagent avec la requête, dans une partie du corps multipart/form-data portant un nom ; la clé image reprend ce nom. C'est le même vivier de parties nommées que les gabarits, donc plusieurs articles dessinent la même image à des tailles et à des places différentes, pour un seul envoi et une seule copie dans le fichier produit. Le cadre est un rectangle en points ; l'ajustement dit si l'image remplit ce rectangle ou si elle garde ses proportions. L'article accepte les mêmes réglages de placement que les autres : choix des pages, matrice, rotation et calque.

Chaque clé, avec son défaut

La référence : quelles clés sont obligatoires, lesquelles sont facultatives, ce que vaut chacune par défaut et quelles combinaisons le serveur décline.

Clés obligatoires : image, chaîne, le nom de la partie fournie ; rect. Facultatives : fit, valant stretch (défaut, l'image remplit le rectangle) ou contain (l'image garde ses proportions, grandit jusqu'à toucher la largeur ou la hauteur, et se centre dans le reste) ; pages, tableau d'entiers en base 1, défaut vide pour toutes les pages ; transform, six nombres ; rotate, degrés dans le sens trigonométrique autour du centre de la boîte ; layer, nom d'un calque déclaré. Refus croisé : transform et rotate ensemble. Un nom d'image que la requête ne fournit pas donne une réponse 400.

Une requête entière qui le dessine

Envoyez ceci tel quel et un PDF revient. Rien n'en a été retiré.

{
  "items": [
    {
      "type": "image",
      "image": "logo.png",
      "rect": {"llx": 72, "lly": 660, "urx": 192, "ury": 780},
      "fit": "contain"
    }
  ]
}

La ligne qui l'envoie, en trois langages

Glossaire

octet

L'unité dans laquelle se compte le poids d'un fichier, comme un colis se compte en grammes. Mille octets font un kilo-octet, un million font un méga-octet — la taille d'une photo prise avec un téléphone. Un PDF d'une page pèse ici entre six mille et cent vingt mille, donc cent PDF tiennent dans la place de cinq photos.

requête

Un appel au service : vous envoyez ce que le document doit dire, et vous recevez le document. Votre facture compte ces appels, un par document. Le nombre de pages d'un document n'est jamais compté.

formulaire multipart

Une façon d'emballer plusieurs choses dans un seul appel : chacune reçoit un nom et voyage dans sa propre partie, et ce peut être du texte comme des fichiers. C'est ce qu'emploie une page web pour envoyer une photographie, et ce qui porte la description d'un document à côté des images qu'il dessine.

calque

Un groupe nommé de choses dessinées sur une page, que le lecteur peut afficher ou masquer, comme un calque posé sur un plan. Un plan peut garder ses cotes sur l'un et ses notes sur l'autre, et un calque peut être réglé pour s'afficher à l'écran et rester hors de l'impression.

Tous les mots que le site explique