Créer une bibliothèque qui lit et écrit des fichiers d'image en couches sans perte de données

## Installer seulement les dépendances utiles à la tâche et utiliser les commandes du projet Lisez la documentation destinée aux contributeurs avant de modifier le code. Utilisez le gestionnaire d'environnement et les commandes de tâches du dépôt plutôt que de lancer des outils depuis un environnement d'exécution sans rapport. Configurez uniquement les groupes de dépendances nécessaires à la tâche : - installez les dépendances de développement par défaut pour l'analyse et les tests ; - ajoutez le groupe de rendu facultatif lorsque la composition d'images ou la rastérisation est concernée ; - incluez les groupes de documentation uniquement lorsque vous générez la documentation ; - prévoyez que certains paquets scientifiques ou graphiques facultatifs puissent être indisponibles avec de nouvelles combinaisons d'environnement d'exécution et de système d'exploitation. Utilisez les commandes de référence pour : - compiler les modules d'extension et produire les artefacts de distribution ; - exécuter toute la suite de tests avec mesure de la couverture ; - exécuter un test unique à l'aide de son identifiant de nœud ; - exécuter les tests sans mesurer la couverture lorsque vous mesurez un comportement ciblé ; - exécuter les contrôles de style, le formatage et les vérifications statiques des types ; - générer la documentation HTML et examiner le répertoire de sortie indiqué dans sa documentation. Ne considérez pas les dépendances facultatives de rendu comme des exigences fondamentales de l'analyse. Lorsqu'une opération facultative est demandée sans ses dépendances, fournissez une instruction d'installation claire. ## Séparer la lecture et l'écriture binaires de bas niveau de l'API destinée à l'utilisateur Séparez l'analyse binaire de bas niveau de l'interface utilisateur de haut niveau. La couche de bas niveau : - lit et écrit le format binaire brut conformément à sa spécification ; - modélise les en-têtes, les enregistrements, les blocs étiquetés, les descripteurs, les ressources d'image, les masques, les canaux et les données de compression ; - expose des méthodes de sérialisation explicites `read(fp)` et `write(fp)` ; - préserve les données inconnues qui ne peuvent pas encore être interprétées. La couche de haut niveau : - enveloppe les structures documentaires de bas niveau dans des interfaces faciles à utiliser ; - reconstitue les arborescences d'objets destinées à l'utilisateur à partir d'enregistrements binaires plats ; - expose les types de calques, les effets, les masques, le rendu et les opérations sur les documents ; - diffère les analyses coûteuses jusqu'à l'accès aux données lorsque le contrat le permet. Le code interne doit importer les définitions concrètes de bas niveau depuis les modules qui les définissent. Les utilisateurs externes doivent employer les exportations prises en charge par le paquet. N'exposez pas les détails de représentation de bas niveau dans les méthodes publiques sans motif de compatibilité. ## Lire et écrire les sections du fichier dans l'ordre et garder les données inconnues Traitez l'ordre des sections, les longueurs, les signatures et les largeurs numériques comme des éléments du contrat du format de fichier. Un fichier d'image en couches classique contient cinq sections séquentielles : 1. Un en-tête de fichier de taille fixe contenant la signature, la version, les dimensions, les canaux et le mode colorimétrique. 2. Des données de mode colorimétrique, comme les palettes indexées. 3. Des ressources d'image, comme les profils colorimétriques, les repères et les miniatures. 4. Des informations sur les calques et les masques contenant les enregistrements de calque, les données de canal et les blocs étiquetés. 5. Les données de l'image composite aplatie. Validez les tailles fixes d'en-tête, telles que 26 octets lorsque la spécification l'exige. Lisez et écrivez les sections dans l'ordre ; ne déduisez pas leurs limites à partir d'objets en mémoire plus pratiques. Renvoyez le nombre d'octets écrits par les méthodes de sérialisation afin que les appelants puissent vérifier la comptabilisation des tailles. Lors d'un aller-retour, préservez les charges utiles inconnues sous forme d'octets au lieu de les écarter. ## Reconstituer les groupes de calques à partir de la liste plate d'enregistrements Lorsque le format stocke une hiérarchie sous forme de liste plate, interprétez les enregistrements de délimitation explicites au lieu de supposer uniquement la contiguïté. Reconnaissez les marqueurs de début et de fin de groupe, puis reconstruisez les relations parent-enfant au moyen d'une pile ou d'une machine à états équivalente et vérifiée. Testez au minimum : - des enregistrements ordinaires hors des groupes ; - un groupe contenant plusieurs enfants ; - des groupes imbriqués ; - des groupes vides ; - des marqueurs de délimitation incorrects ou déséquilibrés ; - la préservation de l'ordre initial des enregistrements. Conservez la liste plate des enregistrements de bas niveau pour la sérialisation tout en exposant une arborescence par l'interface de haut niveau. La reconstitution de l'arborescence ne doit pas modifier des enregistrements binaires sans rapport. ## Ajouter des blocs étiquetés via un registre et laisser intacts ceux non pris en charge Dotez les structures binaires d'un contrat de base commun, avec lecture au niveau de la classe et écriture au niveau de l'instance. Composez récursivement les structures complexes à partir de petites primitives. Utilisez systématiquement les fonctions de classes de données typées pour : - les initialiseurs générés ; - la validation des champs ; - les annotations de type ; - les représentations maîtrisées ; - la conversion prévisible en tuple ou en séquence lorsque cela est nécessaire. Maintenez la cohérence des validateurs avec les annotations et utilisez un type de retour représentant la même instance pour les constructeurs fluides ou tenant compte de la classe. Pour les blocs étiquetés extensibles : - utilisez une clé d'étiquette de largeur fixe et la charge utile associée ; - associez les étiquettes connues aux classes de traitement au moyen d'un registre ; - vérifiez la présence d'une étiquette avant de lire ses données typées ; - conservez les blocs non pris en charge intacts pour pouvoir les écrire ultérieurement ; - séparez l'accès public simplifié de l'accès interne aux enregistrements. N'enregistrez pas de classe de traitement qui consomme des octets qu'elle ne peut pas réécrire fidèlement. ## Accélérer la compression et les calculs de pixels sans casser la solution de repli Mesurez les chemins sensibles aux performances avant de les optimiser. Utilisez des codecs compilés pour les opérations coûteuses de compression ou de décompression lorsqu'ils sont disponibles, tout en conservant une solution de repli correcte entièrement écrite dans le langage. Utilisez le chargement différé pour les masques, les effets et les données de canal lorsque l'analyse différée préserve la sémantique. Utilisez la vectorisation des tableaux pour les calculs volumineux de pixels et de modes de fusion lorsqu'elle améliore le débit. Chaque optimisation doit préserver : - la compatibilité de la sortie binaire ; - le comportement des erreurs ; - les résultats déterministes ; - la solution de repli non optimisée ; - la prise en charge des environnements dans lesquels les dépendances compilées ou facultatives ne sont pas disponibles. Testez les mises en œuvre optimisées et de repli avec les mêmes jeux de données de test. Ne modifiez jamais silencieusement les résultats pour gagner en vitesse. ## Tester les modifications en lisant, écrivant et relisant les fichiers, et ajouter des annotations de type Organisez les tests en suivant la structure du paquet, en séparant les tests binaires de bas niveau des tests de l'interface de haut niveau. Conservez des fichiers binaires de test représentatifs dans un répertoire dédié et paramétrez les tests sur plusieurs fichiers. Utilisez la validation aller-retour comme invariant principal : 1. Lisez le fichier binaire. 2. Modifiez un champ contrôlé. 3. Écrivez le fichier. 4. Relisez le résultat. 5. Vérifiez la modification prévue et la préservation des données sans rapport. Ajoutez des annotations de type appropriées à chaque nouvelle signature de fonction. Maintenez la cohérence des validateurs de classes de données avec les annotations. Utilisez le type de compatibilité du projet pour les méthodes qui renvoient une instance de leur propre classe. Exécutez des tests ciblés pendant le développement, puis la suite complète pertinente, les contrôles de style, le formatage et la vérification des types avant de terminer. Examinez les variations de couverture au lieu d'utiliser uniquement le pourcentage de couverture comme preuve d'exactitude. ## Publier via le processus automatisé et signaler clairement ce qui n'est pas pris en charge Choisissez les versions publiées conformément à la norme de gestion des versions documentée du projet, notamment les formes finale, de prépublication et de post-publication. Résumez les changements intervenus depuis l'étiquette précédente dans le journal des modifications, sous le titre de la nouvelle version. Utilisez exactement le modèle de branche de publication exigé par l'étiquetage automatisé. Ouvrez une demande de publication visant la branche principale et ne la fusionnez qu'après approbation. Laissez l'automatisation configurée étiqueter la validation fusionnée exacte, construire les distributions, créer la publication hébergée et publier dans le registre de paquets. Ne créez pas d'étiquette manuelle lorsque le processus de publication gère l'étiquetage. Assurez-vous que les informations d'authentification de l'automatisation disposent uniquement des autorisations minimales nécessaires pour déclencher les processus en aval, et ne les exposez jamais. Avant d'affirmer qu'une fonction marche, vérifiez les limites documentées concernant : - le rendu du texte en l'absence de moteur de polices ; - les opérations d'ajustement prises en charge et non prises en charge ; - le sous-ensemble des effets de calque mis en œuvre ; - l'extraction par opposition à la modification des objets intégrés ; - la préservation sans interprétation des données inconnues. Indiquez explicitement les comportements non pris en charge au lieu de les approximer silencieusement. Terminez en signalant les tests exécutés, les chemins facultatifs non testés, les risques de compatibilité et toute limite qui affecte la modification demandée.