WriteImage

The WriteImage function is used to save the current image to a local device or an FTP server. Optionally, an SVG file may also be created, which includes the overlay graphics on top of the image.

Note:
  • You can save the file to the selected Storage location while Online or Offline.
  • If your job is configured to save a large number of image files, it is recommended that you select FTP Server for the Storage setting. If a large number of image files are saved on an In-Sight device (for example, if the Event parameter is set to AcquireImage (A0), and the AcquireImage function's Trigger Mode is set to Continuous), you may experience severe issues due to lack of available memory storage.

WriteImage Inputs

Parameter Description
Image Specifies a reference to a cell containing an Image data structure. The default reference is to the Image data structure in cell A0.
Event

Specifies the event that forces an update.

This parameter must be a reference to one of the following:

  • The Image data structure in cell A0, containing the AcquireImage function.
  • A cell containing an Event function.
  • A cell containing a Button function.
Note: By default, the Event reference value is 0. If you don't change the default value, a button, labeled "Write," will be automatically created and referenced when WriteImage is initially inserted into the spreadsheet.
Storage

Specifies whether you want to save the image to a local device or an FTP server.

Depending on the connected device and the function's Storage setting, the files are saved in different location.

Storage Setting Connected Device Saved Location
Local Device In-Sight Device
  • In-Sight device
  • SD card installed to the In-Sight device
Note: You must use FTP software, such as FileZilla Client, to view files. For more information, see How to View Files Stored on In-Sight Device.

Emulator

In-Sight ViDi PC

PC
  • PC
FTP Server Any device
  • Specified FTP server
Server

Specifies the server name (or IP address) on the network where the image file will be written. An FTP server can be an In-Sight emulator or any other device recognized as an FTP server on the network.

Note:
  • This option is enabled only when the FTP Server is the selected Storage type.
  • If a particular port is required, you can append it to the server name. For example, the FTP server uses port 50021, enter “127.0.0.1:50021”.
User Name

Specifies a valid user name of the FTP server. When this field is left blank, "admin" is used.

Note: This option is enabled only when the FTP Server is the selected Storage type.
Password

Specifies the password of the FTP server. The password is case-sensitive. If the FTP server does not have a password, you can leave this field blank.

Note:
  • This option is enabled only when the FTP Server is the selected Storage type.
  • For security purposes, the entered password will be masked with "*" in the property sheet and the formula bar.
  • The password will be saved in the job file in encrypted form.
File Path

Specifies the location where you want to save the file.

  • To save the files to the SD card installed to the In-Sight vision system, enter sdcard in the File Path field.
  • When saving to the PC, the file can be written to any location where you have operating system write permissions. You can enter a hardcoded path (e.g. X:/, X:/Subdir), UNC path (e.g. //Cognex/shared/), mapped drive (e.g. M:/Subdir), or relative path (../../Subdir) to this field.
  • If the path does not exist on the In-Sight device or the PC, the function returns #ERR. If the path or FTP credentials are invalid on the FTP server, the function does not return #ERR.
  • When writing a file to an FTP server, you can also specify a file path.

When this field is left blank, the file is sent to the following default location:

  • In-Sight device: Device's root directory.
  • Emulator, In-Sight ViDi PC: C:/ProgramData/Cognex/In-Sight/In-Sight ViDi PC/pubfs
  • FTP Server: The specified FTP server's default directory.
File Name

Specifies the name of the image file; also defines the name of the SVG file.

Note:
  • Follow the operating system's restrictions on the legal characters.
  • You can format the File Name's append value parameter. For more information, see the Format the Value Parameter section in this topic.
File Type

Specifies the file format of the image that will be saved.

0 = BMP (default) Windows bitmap format (.BMP extension).
1 = JPEG Standard encoded JPEG format (.JPG extension).
Max Append Value The maximum number (0 to 9999999; default = 999) of unique image files that can be written using the specified File Name. A counter will increment itself as each image file is written, and be added to the end of the specified File Name if no format specifier is used; otherwise, the counter will be added at the location of the format specifier. The counter automatically resets itself when it equals the Max Append Value; existing image files on the target system will be overwritten by new files of the same name. If the value is set to -1 or an out of range value, then no counter will be appended to the File Name.
Reset

Restarts the counter that is appended to the specified File Name to 0. After reset, the existing image files on the target location will be overwritten by new files with the same name.

0 = OFF (default) The counter will continue to increment as each image is written out, up to the Max Append Value.
1 = ON The counter will reset to 0.
Note: By default, the Reset checkbox is not selected. If you don't change the default setting, a button, labeled "Reset" will be automatically created and referenced when the WriteImage function is initially inserted into the spreadsheet.
Overlay Graphics

Specifies whether an SVG file with the overlay graphics is created. To view the SVG file and image file, open the SVG file with a Web browser that supports the SVG file type. The SVG file contains an internal link to the acquired image associated with it, and when the browser opens the SVG file, it follows the link to open and display the acquired image along with the overlay graphics.

0 = OFF Only the image will be transferred.
1 = ON (default) Both image and an SVG file will be transferred. When enabled, the SVG file containing the graphic overlay data will be saved into the same directory specified for the images. Use a Web browser to view the overlay graphics data and images together.
Note:
  • When enabled, the SVG file will use the name specified in the File Name parameter.

  • Due to the graphics being rendered by a third-party application, such as a Web browser, the overlay graphics data will not be an exact pixel-for-pixel match.

WriteImage Outputs

Returns
  • A WriteImage data structure that will write the image data contained in the specified Image data structure to a local device or an FTP server, whenever the referenced Event is updated.
  • Returns #ERR if any input parameters are invalid, or if the file queue is full.
  • Returns #ERR if the In-Sight D900 series vision system's memory storage is full.
Note: Any invalid FTP server, path or file name will not return an #ERR.
Tip:

If you hover over #ERR, the following error message will be displayed:

Message Error Reason
#ERR: Cannot open file: file path/file name The specified File Path or File Name parameter is incorrect (i.e. the file path is not created).
#ERR: Error 0:7:2: file path/file name The vision system's memory storage is full.
Results

When WriteImage is initially inserted into the spreadsheet, and if the Event and/or Reset parameters are in the default settings, the Write and/or Reset buttons will be automatically created and referenced in the spreadsheet.

Format the Value Parameter

You can format the value parameter so that the names are aligned, by using the '|' character. If a '|' is used, the value will either be zero or blank filled. If the character immediately following a '|' is 0, the format will be zero-filled; otherwise, it will be blank filled. The next character(s) will indicate how may 0 or ' ' to insert. If the filename contains multiple ‘|’ characters, the last one will be used as the format indicator. If the ‘|’ character is not followed by a digit, then the ‘|’ will be used as part of the name, following any operating system's restrictions.

If File Name is set to MyImage, the saved file names will be:

If File Name is set to MyImage|03, the saved file names will be:

If File Name is set to MyImage|3, the saved file names will be:

If the '|' is in the middle of the file name , the Append Value will be inserted inline. For example, if File Name is set to Fail_Image|03JobX, the saved file names will be: