# Référence de l’API et du code source JavaScript pour fonction Script

Respectez les instructions suivantes pour écrire du code source JavaScript avec la fonction Script. L’implémentation de JavaScript respecte la version 5 de la norme ouverte approuvée par l’ECMA, également appelée ECMAScript 5 (ECMA5).

## Constructeur

Le code source JavaScript doit présenter une ligne "module.exports" qui est une fonction qui représente le constructeur de l’outil. Cette fonction est appelée, sans arguments, après la compilation du script, qui initialise une instance de l’objet Tool.

Remarque :

- Le nom de la fonction « Outil » dans les exemples suivants est arbitraire (et n’a aucun effet sur le fonctionnement de la fonction Script) et est utilisé dans tous les exemples et scripts In-Sight. De nombreux autres noms peuvent être donnés au nom de la fonction « Outil » mais le nom doit être utilisé systématiquement, de façon cohérente, dans le code source d’une fonction Script . De plus, dans les exemples ci-dessous, le mot-clé « ce » fera référence à l’objet Outil créé et initialisé à l’aide de la fonction « constructor ».
- Basées sur l’implémentation de JavaScript par In-Sight, les méthodes Script (c’est-à-dire, « constructor », « run », « save », « load » et/ou « draw ») peuvent être appelées plusieurs fois lors de la modification de la fonction Script ou de la fermeture de la Boîte de dialogue Modifier le script. Par exemple, une fois qu’un script a été créé dans la boîte de dialogue Modifier le script, au moment d’appuyer sur le bouton Enregistrer, la méthode « run » peut être exécutée plusieurs fois pour s’assurer qu’elle compile correctement et pour renvoyer des résultats : plusieurs messages peuvent donc s’afficher dans le fichier console.log.

Par exemple :

    function Tool() {
      // Initialize the tool state
      this._partTotal = 0;
    }
    module.exports = Tool;

## Méthode Run

L’objet Tool doit définir une méthode "run", appelée à chaque fois que la fonction Script est exécutée. Dans le cas contraire, la fonction Script renvoie #ERR. Les arguments de la fonction Script sont transmis à la méthode Run du script dans l’ordre où ils sont spécifiés.

L’exemple suivant illustre la syntaxe recommandée pour définir la méthode Run :

    Tool.prototype.run = function(a, b) {
      return "The average is" + (a+b)/2;
    };

Remarque :

- Toutes les fonctions JavaScript sont variadiques, c’est pourquoi la méthode Run du script n’a pas besoin de déclarer le même nombre d’arguments que ceux transmis à la fonction Script. La fonction Script peut également accéder à un nombre variable d’arguments, en utilisant le tableau "arguments".
- Basées sur l’implémentation de JavaScript par In-Sight, les méthodes Script (c’est-à-dire, « constructor », « run », « save », « load » et/ou « draw ») peuvent être appelées plusieurs fois lors de la modification de la fonction Script ou de la fermeture de la Boîte de dialogue Modifier le script. Par exemple, une fois qu’un script a été créé dans la boîte de dialogue Modifier le script, au moment d’appuyer sur le bouton Enregistrer, la méthode « run » peut être exécutée plusieurs fois pour s’assurer qu’elle compile correctement et pour renvoyer des résultats : plusieurs messages peuvent donc s’afficher dans le fichier console.log.

## Valeurs retournées par la méthode Run

La méthode Run peut renvoyer les types de valeurs suivants :

- Un nombre
- Vrai (1) ou faux (0)
- Une chaîne de caractères
- Une structure de données Binary
- Une structure de données Blob, Edge, Histogram, ou Vision Data Access functions Patterns
- Un objet de forme (Shape)
- Un objet
- Une image
- null, undefined ou pas d’instruction « return » (même traitement qu’un objet vide).

Remarque :

- Lorsqu’un nombre ou une chaîne de caractères est renvoyé, la fonction Script affiche un nombre ou une chaîne de caractères comme résultat de sortie.
- Lorsqu’un objet est renvoyé, la fonction Script affiche une structure de données Object.
- Lorsqu’un tableau est renvoyé, la fonction Script affiche une structure de données Array.

## Méthode Draw

La fonction Script utilise une méthode "draw" qui lui permet de générer des graphiques similaires aux fonctions Image. La méthode Draw accepte un seul argument, qui est un objet de contexte graphique.

Remarque :

- La méthode Draw est facultative et peut être omise si aucun graphique n’est tracé.
- Si l’une des méthodes « draw », « save » ou « load » lève une exception, celle-ci est journalisée dans la console et la méthode se ferme à ce moment-là. Cependant, la fonction Script ne renvoie pas nécessairement #ERR dans cette situation : elle renvoie le résultat de la méthode « run », ou #ERR si la méthode « run » lève une exception ou si le code ne peut pas être compilé.
- Basées sur l’implémentation de JavaScript par In-Sight, les méthodes Script (c’est-à-dire, « constructor », « run », « save », « load » et/ou « draw ») peuvent être appelées plusieurs fois lors de la modification de la fonction Script ou de la fermeture de la Boîte de dialogue Modifier le script. Par exemple, une fois qu’un script a été créé dans la boîte de dialogue Modifier le script, au moment d’appuyer sur le bouton Enregistrer, la méthode « run » peut être exécutée plusieurs fois pour s’assurer qu’elle compile correctement et pour renvoyer des résultats : plusieurs messages peuvent donc s’afficher dans le fichier console.log.

Pour générer des graphiques, procédez comme suit :

- plotArc(centreX, centreY, débutX, débutY, finX, finY, nom, couleur [,afficher])
- plotCircle(X, Y, rayon, nom, couleur [,afficher])
- plotCross(X, Y, angle, largeur, hauteur, nom, couleur [,afficher])
- plotLine(X0, Y0, X1, Y1, nom, couleur [,afficher] [,débutOrnement] [,endOrnement])
- plotPoint(X, Y, nom, couleur [,afficher])
- plotRegion(X, Y, largeur, hauteur, angle, courbe, nom, couleur [,afficher])

Remarque :

- Les paramètres entre crochets sont facultatifs.

- La méthode plotRegion reconnaît des indicateurs supplémentaires qui peuvent faire l’objet d’une opération OU avec les valeurs du paramètre Afficher :

  - 0x100 : Trace uniquement le périmètre de la région, sans les étiquettes des axes X/Y.
  - 0x200 : Trace une région remplie (de couleur unie), sans étiquette des axes X/Y.

  Par exemple, si l’on passe le paramètre Afficher avec une valeur de 0x101, trace une région sans étiquette d’axe, et elle sera systématiquement tracée (qu’il s’agisse ou non de la cellule actuelle). De la même façon, en passant une valeur de 0x201, on trace une région de couleur unie.

- Les paramètres JavaScript ont la même signification que ceux des Fonctions Image, sauf qu’ils ne prennent pas d’image comme premier paramètre. Les graphiques produits par une fonction Script s’affichent sur l’image de la première référence à la cellule trouvée dans la liste des arguments en entrée de la fonction. Si une fonction Script ne reçoit pas d’image en argument d’entrée, ses graphiques s’affichent sur l’image de la première référence à la cellule trouvée dans la feuille.
- Le paramètre "color" est une valeur de couleur RVB 24 bits.
  Compte tenu des valeurs rouge, vert et bleu comprises entre 0 et 255, une valeur de couleur RVB peut être calculée à l’aide de la formule (rouge * 65536) + (vert * 256) + bleu. Exprimé en hexadécimal, au format 0xRRGGBB. Par exemple, la constante hexadécimale 0xFF8020 se traduit par : rouge=255, vert=128, bleu=32.

## Dessin de formes

Outre les graphiques ci-dessus, il existe une méthode Draw pour créer des « formes », qui sont les équivalents des fonctions PlotPolygon et PlotCompositeRegion, où la « forme » peut être l’un des objets Shape pris en charge.

- plotShape(forme, nom, couleur [,afficher])

Remarque : Le polygone ne sera pas affiché si sa longueur dépasse environ 4950 points.

L’exemple suivant illustre la syntaxe correcte de définition de la méthode Draw :

    Tool.prototype.draw = function(gr) {
      gr.plotPoint(this._foundx, this._foundy, "Found Feature", 0xFF00FF);
    };

## Méthodes Save et Load

La fonction Script prend en charge les méthodes "save" et "load", qui permettent à la fonction d’archiver son état interne lorsque le projet est enregistré, et de restaurer l’état de la fonction lorsque le projet est chargé. La méthode save ne prend aucun argument et renvoie un objet qui contient l’état à enregistrer. L’objet est stocké dans le fichier projet, et lorsque le projet est chargé, l’objet est passé comme seul argument de la méthode load de la fonction.

Remarque :

- Les méthodes save et load sont optionnelles et peuvent être omises si l’outil n’enregistre pas d’état dans le projet.

- Si l’une des méthodes « draw », « save » ou « load » lève une exception, celle-ci est journalisée dans la console et la méthode se ferme à ce moment-là. Cependant, la fonction Script ne renvoie pas nécessairement #ERR dans cette situation : elle renvoie le résultat de la méthode « run », ou #ERR si la méthode « run » lève une exception ou si le code ne peut pas être compilé.

- Basées sur l’implémentation de JavaScript par In-Sight, les méthodes Script (c’est-à-dire, « constructor », « run », « save », « load » et/ou « draw ») peuvent être appelées plusieurs fois lors de la modification de la fonction Script ou de la fermeture de la Boîte de dialogue Modifier le script. Par exemple, une fois qu’un script a été créé dans la boîte de dialogue Modifier le script, au moment d’appuyer sur le bouton Enregistrer, la méthode « run » peut être exécutée plusieurs fois pour s’assurer qu’elle compile correctement et pour renvoyer des résultats : plusieurs messages peuvent donc s’afficher dans le fichier console.log.

L’exemple suivant illustre la syntaxe recommandée pour définir les méthodes save (enregistrer) et lead (charger) :

    Tool.prototype.save = function() {
      return {total: this._total, avg: this._average};
    };
    Tool.prototype.load = function(saved) {
      this._total = saved.total;
      this._average = saved.avg;
    };

## Délai d’attente

Chaque méthode JavaScript appelée par la fonction Script (c’est-à-dire le constructeur, run, draw, save et load) est soumise à un délai d’inactivité. Par défaut, le délai d’inactivité est de 10 secondes, avec une granularité par défaut de 1 seconde (le délai d’inactivité est en millisecondes, avec une valeur minimale de 1 et un maximum de 60000 ; la granularité est également en millisecondes, avec un minimum de 1 et un maximum de 10000). Si l’une des méthodes prend plus de 10 secondes à s’exécuter, elle est abandonnée, ce qui a le même effet qu’une exception avec un message indiquant qu’un délai d’inactivité a été dépassé.

Remarque : L’objectif du délai est d’éviter de bloquer la caméra In-Sight dans une boucle infinie créée par inadvertance dans le script, plutôt que d’avoir à passer un délai d’inactivité spécifique à la fonction pour limiter la durée d’exécution d’un projet, comme avec le paramètre Délai d’attente de la fonction FindPatMaxRedLine. Pour ce type de fonctionnalité, utilisez la méthode hrtime([heure]) dans le script pour vérifier régulièrement le temps écoulé et décider si la fonction doit se poursuivre.

Il est également possible de modifier manuellement la durée du délai d’inactivité pour toutes les cellules de script, comme dans l’exemple suivant :

                function Script() {
    }

    module.exports = Script;
    Script.prototype.run = function (arg0) {

                // Find the script configuration object.
    var scriptConfig = process.binding("InSight.Camera").config.script;

                // Change the (shared) Script timeout.
    scriptConfig.toolTimeout = 3000 /*ms*/;
    return true;
    }

## Chemins d’accès des fichiers

Dans cette rubrique, pour les fonctions JavaScript qui prennent un nom de fichier ou un chemin de répertoire, celui-ci peut être soit un nom simple (référence à des fichiers présents sur le système de fichiers local), soit une URL (en utilisant le modèle FTP pour faire référence à des fichiers et des répertoires sur un serveur FTP).

Lorsqu’une URL est utilisée, elle doit suivre le format d’URL FTP, spécifié dans la RFC 1738 : ftp://<utilisateur>:<mot de passe>@<hôte>:<port>/<chemin-url>

Remarque : Certaines informations peuvent être exclues :"<utilisateur>:<mot de passe>@", ":<mot de passe>", "<port>" et "/<chemin-url>".

## Modules Script

Tout le code JavaScript In-Sight est chargé sous forme de modules qui se voient attribuer la confidentialité de leur portée supérieure ; des fonctions d’importation d’objets singleton d’autres modules ; et d’exportation de leur propre API. Ce format est utilisé pour charger le code JavaScript contenu dans une fonction Script, ainsi que pour charger des modules de script externes à partir de fichiers.

Remarque : Bien que le système de modules soit basé sur ceux de CommonJS et NodeJS, Cognex ne garantit pas la compatibilité avec les modules conçus pour ces systèmes.

L’exemple suivant illustre comment importer le code source :

                /*
    This script returns the roots of a quadratic equation, given the coefficients a,b,c from a standard form equation.
    */
    function Script() {

    }
    /*
    This is a required statement, and enables the Spreadsheet to call the Script function, which initializes this cell.
    */
    module.exports = Script;
      var quad = require('quadratic'); 	// Imports the module
    /*
    This is where the quadratic module can be put to use.
    */
    Script.prototype.run = function() {
        var a = 1, b = 4, c = 2;
        return quad.roots(a,b,c); //Put the module to use
    }

Remarque : Si le fichier .js spécifié n’est pas lisible lorsque la fonction require() est appelée, la fonction require() renvoie la valeur "undefined" et ne lève pas d’exception.

## Portée globale

Un module de portée globale est unique à ce module, ce qui signifie que toutes les variables libres définies par le module sont visibles par ce module.

## Fonction "require"

Dans un module, "require" est une variable libre qui agit comme une fonction. La fonction "require" accepte en argument un identifiant de module et renvoie l’API exportée du module importé. Si le module demandé ne peut pas être renvoyé, la fonction "require" renvoie la valeur "undefined".

## Variable "module"

Dans un module, il existe une variable libre, "module", qui est un objet (Object). L’objet "module" possède une propriété "exports" qui représente l’API exportée du module. Initialement, cette propriété est un objet vide.

Un module peut simplement ajouter des propriétés à l’objet "module.exports" créé par défaut pour exporter son API. Un module peut également affecter un nouvel objet à la propriété "module.exports" pour exporter un objet différent en tant que son API, plutôt que d’utiliser l’objet "exports" vide créé par défaut.

## Variable "exports"

Dans un module, il existe une variable libre appelée "exports", qui initialise la valeur de "module.exports".

Remarque : Cette variable est founie à titre utilitaire, permettant aux scripts d’ajouter simplement des propriétés à l’objet "exports" plutôt que d’avoir à spécifier "module.exports".

## Identifiant de module

L’identifiant de module est soit le nom d’un fichier présent sur le système de fichiers local du système de vision In-Sight, soit le nom d’un fichier sur un serveur FTP, comme spécifié dans la section « Chemins d’accès des fichiers ».

Remarque : Si le nom est spécifié sans extension de fichier, l’extension ".js" est automatiquement ajoutée au fichier lors de son chargement.

## Structures de données en entrée/sortie

Les structures de données Blob, Edge, Histogram, et Vision Data Access functions Patterns sont acceptées à la fois en entrée et en sortie d’une fonction Script. Ces structures de données sont en lecture seule et ne peuvent pas être créées ou modifiées par le code source JavaScript. Chacune des structures de données expose des méthodes qui correspondent aux Vision Data Access functions Vision Data Access functions prises en charge par la structure de données concernée.

Par exemple, une structure de données Blobs prend en charge les méthodes suivantes :

- blobs.getNFound() – renvoie le nombre de blobs trouvés.
- blob.getAngle(index ) – renvoie l’angle du centre de gravité d’un blob indexé.
- blob.getArea(index ) – renvoie la surface (en pixels) d’un blob indexé.

## Objets Shape

Un objet de forme, Shape, peut être passé à une fonction Script comme argument (par exemple, par la référence à une fonction EditRegion), et peut être renvoyé comme valeur de retour. Les objets de forme sont créés à l’aide de constructeurs membres du module ’cognex’.

La figure suivante illustre comment les objets de forme peuvent être créés :

                function Example()
    {
    }
    var cognex = require('cognex');
    module.exports = Example;

    Example.prototype.run = function(x, y)
    {
      var annulus = new cognex.Annulus(150, 250, 25, 45);
      var circle = new cognex.Circle(50, 250, 30);
      var fixture = new cognex.Fixture(230, 300, 45);
      var line = new cognex.Line(270, 530, 290, 50);
      var point = new cognex.Point(330, 500);
      var polygon = new cognex.Polygon();
      polygon.add(340,230);
      polygon.add(390,210);
      polygon.add(370,230);
      polygon.add(390,250);
      var region = new cognex.Region(440, 300, 40, 50, 30, 45);
      this.shapes = [annulus,circle,fixture,line,point,polygon,region];
      return this.shapes;
    }

    Example.prototype.draw = function(gr)
    {
      this.shapes.forEach(function(shape) {gr.plotShape(shape, JSON.stringify(shape), 0xc0ffee*Math.random());});
    }

## Annulus

La fonction du constructeur Annulus nécessite les arguments suivants, et l’objet fournit des propriétés en lecture/écriture avec les mêmes noms :

- X : Le décalage en x.
- Y : Le décalage en y.
- innerRadius : Définit le rayon intérieur.
- outerRadius : Définit le rayon extérieur.

## Circle

La fonction du constructeur Circle nécessite les arguments suivants, et l’objet fournit des propriétés en lecture/écriture avec les mêmes noms :

- X : Le décalage en x.
- Y : Le décalage en y.
- radius : Définit le rayon.

## Repère

La fonction du constructeur Fixture nécessite les arguments suivants, et l’objet fournit des propriétés en lecture/écriture avec les mêmes noms :

- X : Le décalage en x.
- Y : Le décalage en y.
- theta : L’orientation angulaire.

## Ligne

La fonction du constructeur Line nécessite les arguments suivants, et l’objet fournit des propriétés en lecture/écriture avec les mêmes noms :

- x0 : Le décalage sur l’axe X du premier point de terminaison.
- y0 : Le décalage sur l’axe Y du premier point de terminaison.
- x1 : Le décalage sur l’axe X du dernier point de terminaison.
- y1 : Le décalage sur l’axe Y du dernier point de terminaison.

## Point

La fonction du constructeur Point nécessite les arguments suivants, et l’objet fournit des propriétés en lecture/écriture avec les mêmes noms :

- X : Le décalage en x.
- Y : Le décalage en y.

## Polygone

La fonction du constructeur Polygon ne nécessite aucun argument et renvoie un polygone vide. L’objet Polygon propose les propriétés et méthodes suivantes :

- length : Renvoie le nombre de points du polygone. Par exemple, un polygone triangle possède trois points.
- add(x,y) : Ajoute un nouveau point au polygone.
- clear() : Supprime tous les points du polygone.
- remove(n) : Supprime le point spécifié (n) du polygone. Rien ne se passe si l’index est un nombre en dehors de la plage valide des index.
- set(n,x,y) : Définit les coordonnées d’un point (n) du polygone.
- x(n) : Renvoie l’abscisse du point (n) du polygone.
- y(n) : Renvoie l’ordonnée du point (n) du polygone.
- clone() : Renvoie une copie du polygone.

- points : Permet de récupérer ou de définir un tableau de nombres contenant les coordonnées des points du polygone :

  [x0, y0, x1, y1, x2, y2, ...]

  La lecture de cette propriété renvoie un nouveau tableau contenant une copie des points du polygone. Par conséquent, modifier le tableau n’a aucun effet, à moins qu’il ne soit réaffecté à la propriété points.

  Astuce : Lors d’une itération sur les points de polygone, il est bien plus efficace de lire cette propriété une seule fois au début d’une boucle, plutôt que de la lire à chaque itération.

  Lorsque cette propriété est un tableau de valeurs, chaque élément est converti en valeur à virgule flottante à simple précision. Une exception est levée si cette propriété est définie avec une valeur qui n’est pas un tableau d’un nombre pair d’éléments. Le comportement n’est pas défini si une valeur du tableau ne peut pas être convertie en un nombre compris dans la plage de la virgule flottante à simple précision.

- reserve(nombre) : Réserve de l’espace de stockage pour nombre points, mais ne modifie pas la propriété length . Cela permet d’accélérer la création de grands polygones. Une exception est renvoyée si l’espace demandé ne peut pas être alloué.

- translate(tx, ty) : Ajoute les valeurs spécifiées à chaque point du polygone. Chaque point est transformé comme suit :

  nouveau_x = x + tx

  nouveau_y = y + ty

- scale(xÉchelle, yÉchelle) : Multiplie chaque point du polygone par les valeurs spécifiées. Chaque point est transformé comme suit :

  nouveau_x = x * xÉchelle

  nouveau_y = y * yÉchelle

- transform(m00, m01, m10, m11, tx, ty) : Applique une matrice de transformation aux points du polygone. Chaque point est transformé comme suit :

  nouveau_x = x * m00 + y * m01 + tx

  nouveau_y = x * m10 + y * m11 + ty

Si un index (n) est spécifié, le premier point a un index égal à zéro. Si l’index (n) n’existe pas, le getter renvoie zéro, tandis que le setter renvoie une erreur d’index hors limites, sauf spécification contraire.

## Région

La fonction du constructeur Region nécessite les arguments suivants, et l’objet fournit des propriétés en lecture/écriture avec les mêmes noms :

- X : L’offset en X de l’origine.
- Y : L’offset en Y de l’origine.
- w : La dimension de l’axe des x de la région.
- h : La dimension de l’axe des y de la région.
- angle : L’orientation angulaire, en degrés.
- curve : Écart angulaire entre l’axe X de la région et la ligne de la limite opposée.

## Objet Process

Dans tout module, une variable libre "process" fournit à un objet les méthodes suivantes.

## uptime()

Cette méthode renvoie le nombre de secondes écoulées depuis la mise en route du système, sous forme de valeur à virgule flottante, avec une précision inférieure à la microseconde.

Remarque : La précision dépend de celle de l’horloge à quartz du système et d’autres facteurs, c’est pourquoi aucune précision spécifique n’est garantie.

La figure suivante illustre comment la méthode peut être utilisée :

                var start = process.uptime();
    someTimeConsumingFunction();
    var elapsedSeconds = process.uptime() - start;

## hrtime([heure])

Cette méthode renvoie l’heure actuelle dans un tableau de tuples haute résolution (secondes, nanosecondes), où le premier élément est un nombre entier représentant les secondes, et le second élément est un nombre entier représentant les nanosecondes écoulées depuis le début de la seconde. Cette méthode est principalement utilisée pour mesurer le temps entre des intervalles.

Remarque : La précision dépend de celle de l’horloge à quartz du système et d’autres facteurs, c’est pourquoi aucune précision spécifique n’est garantie.

Si cette méthode est appelée sans argument, l’heure renvoyée est relative à la date de mise en route du système de vision In-Sight. Si la méthode est appelée avec le résultat d’un appel précédent de hrtime(), l’heure renvoyée correspond au décalage par rapport à l’heure précédente.

La figure suivante illustre comment la méthode peut être utilisée :

                var start = process.hrtime();
    someTimeConsumingFunction();
    var diff = process.hrtime(start);
    var elapsedSeconds = diff[0] + diff[1] / 1e+9

## sleep(ms)

Cette méthode indique que la fonction Script doit être en veille pendant le nombre spécifié de millisecondes.

Remarque : La période de veille est interrompue si un délai d’inactivité ou d’attente s’écoule avant la fin de la période de veille.

## memoryUsage()

Cette méthode renvoie un objet qui possède deux propriétés :

- heapTotal : Indique la taille totale du tas.
- heapUsed : Indique la quantité actuellement utilisée du tas.

## Objet Console

Dans tout module, une variable libre "console" fournit à un objet les méthodes suivantes.

Remarque : Les messages de la console s’affichent dans le volet Sortie qu’il est possible d’ouvrir depuis le menu Affichage.

## console.log(message)

Cette méthode affiche un message, sous forme de texte normal, dans le volet de sortie.

## console.warn(message)

Cette méthode imprime un message, avec le texte en noir sur un arrière-plan jaune, dans le volet de sortie.

## console.error(message)

Cette méthode imprime un message, avec le texte en noir sur un arrière-plan rouge, dans le volet de sortie.

## Module de système de fichiers

Le module "fs" permet d’accéder aux fichiers du système de fichiers local d’un système de vision In-Sight, ainsi qu’à ceux se trouvant sur les serveurs FTP distants.

Remarque : Toutes les méthodes du module du système de fichiers se terminent par « Sync » pour indiquer qu’elles sont « synchrones », ce qui signifie que l’exécution du script dans la fonction Script est bloquée jusqu’à la fin de l’opération sur le fichier.

Ce module est obtenu à l’aide de la fonction "require" :

     var fs = require("fs");

L’objet système de fichiers propose les méthodes suivantes.

Remarque :

- La visibilité du type de fichier est la même entre le code source d’une fonction Script et les types de fichiers pris en charge par le système de vision (par exemple, .txt, .htm, .xml, .js, .css, .rtf et .json). Cependant, en cas d’accès à un serveur FTP tiers, les utilisateurs autorisés peuvent lire/écrire d’autres types de fichiers.
- En raison de la multitude de configurations de serveur FTP possibles, Cognex recommande de vérifier le serveur FTP et les chemins de fichier prévus, avant d’utiliser les méthodes du module de système de fichiers (en particulier appendFileSync, car elle s’appuie sur existesSync, ReadFileSync et WriteFileSync). Par exemple, dans certaines configurations de serveur FTP de type « à l’aveugle », la méthode existFileSync peut renvoyer FAUX pour un fichier existant, et la méthode readFileSync peut échouer, ce qui entraîne une perte de données.

## appendFileSync(nom de fichier, données)

Cette méthode permet d’ajouter les données à un fichier, s’il existe, ou de les écrire dans un nouveau fichier. Si le paramètre de données est un tableau de type JavaScript, tel que Uint8Array ou DataView, celles-ci sont écrites dans le fichier sous forme de données binaires. Dans le cas contraire, elles sont converties en chaîne de caractères et écrite dans le fichier sous forme de chaîne UTF-8.

## existsSync(nom de fichier)

Cette méthode renvoie VRAI si le fichier spécifié existe.

## readFileSync(nom de fichier [,"binary"])

Cette méthode lit et renvoie l’ensemble du contenu du fichier dont le nom est passé en argument. Le contenu du fichier est lu sous forme de texte UTF-8 et renvoyé sous forme de chaîne de caractères. Si l’argument facultatif "binary" est utilisé, le contenu du fichier est renvoyé sous forme de données binaires dans un type DataView. Par exemple :

    var binaryData = fs.readFileSync('ftp://server/xyz.dat', "binary");

Remarque : Cette méthode lève une exception en cas de tentative de lecture d’un fichier système.

## readdirSync(chemin)

Cette méthode lit le contenu d’un répertoire et renvoie un tableau constitué de noms de fichiers. Pour lire uniquement le contenu d’un répertoire du système de vision In-Sight, indiquez une chaîne vide ou "." ; pour lire le contenu du répertoire d’un serveur FTP, indiquez uniquement l’URL FTP.

## statSync(chemin)

Cette méthode prend un fichier ou un répertoire et renvoie un objet avec la propriété suivante :

- size : La taille, en octets, du fichier.

Remarque : Si le fichier n’existe pas, cette fonction renvoie un objet de taille nulle, size=0, au lieu de lever une exception.

## unlinkSync(nom de fichier)

Cette méthode est utilisée pour supprimer le fichier. Cependant, si le fichier n’existe pas, la méthode ne fait rien.

## writeFileSync(nom de fichier, données)

Cette méthode écrit l’ensemble du contenu du fichier et écrase un fichier existant (si le fichier n’existe pas, il est créé). Si le paramètre "données" est un tableau typé JavaScript, tel que Uint8Array ou DataView, elles seront écrites dans le fichier sous forme de données binaires. Dans le cas contraire, elle sont converties en chaînes de caractères (si elles ne sont pas déjà des chaînes de caractères) et écrites dans le fichier sous forme de chaîne UTF-8.

Remarque : Cette méthode lève une exception en cas de tentative de lecture d’un fichier système.