WriteImage

Use the WriteImage function to save the current image to a local device or an FTP/SFTP server. Optionally, you can create an SVG file, 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 you configure the job to save a large number of image files, it is recommended that you select FTP Server or SFTP Server for the Storage setting. If you save a large number of image files on an In-Sight device (for example, if the Event parameter is set to AcquireImage (A0), and the Trigger Mode of the AcquireImage function is set to Continuous), it can cause severe issues due to lack of available memory storage.

The WriteImage function also has a File Cleanup feature that manages the file system of a production line, ensuring that operations do not need to be halted to clear space. When enabled, the cleanup function monitors the file system each time the WriteImage tool is run to maintain a specified percentage of desired free space and remove the oldest files when necessary.

To prevent the cleanup feature from removing system critical files, such as jobs stored on the vision system, make sure that the provided File Path does not point to the root of the user space. If you provide the root as the file path, or the file path is not valid, the tool returns an error.

The cleanup function sorts files in the specified directory and its subdirectories based on the last time they were modified, allowing for the oldest files to be removed first when cleanup is required.

Note: The cleanup function only works as intended if the system has a valid time. Make sure that a time server is properly configured and reachable.

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 needs to be a reference to any event with a timestamp, for example an AcquireImage function.

Note: By default, the Event reference value is 0. If you don not change the default value, a button, labeled "Write," is 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/SFTP server.

The save location depends on the connected device and the Storage setting of the function.

Storage Setting Connected Device Save 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.

If you use SD card storage, make sure that you plug in the SD card before running the job. If you configure SD card storage without plugging in an SD card, the job saves the files to the /sdcard directory of the internal flash drive.

Emulator

In-Sight ViDi PC

PC
  • PC
Note: Saving to a PC is only supported using an FTP server.
FTP Server Any device
  • Specified FTP server
SFTP Server Any device
  • Specified SFTP server
Server

Specifies the server name (or IP address) on the network where the image file is 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 you select FTP Server or SFTP Server as the Storage type.
  • When a particular port is required, you can append it to the server name. For example, if the FTP/SFTP server uses port 50021, enter “127.0.0.1:50021”.
User Name

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

Note: This option is enabled only when you select FTP Server or SFTP Server as the Storage type.
Password

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

Note:
  • This option is enabled only when you select FTP Server or SFTP Server as the Storage type.
  • For security purposes, the entered password is masked with an asterisk (*) in the property sheet and the formula bar.
  • The password is 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 (for example, X:/, X:/Subdir), UNC path (for example, //Cognex/shared/), mapped drive (for example, 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/SFTP credentials are invalid on the FTP/SFTP server, the function does not return #ERR.
  • When writing a file to an FTP server, you can also specify a file path.

  • When writing a file to an SFTP server, you can also specify an absolute file path. If you prefix the path with a tilde (~), you add the file relative to the home directory for the user of the SFTP server.

If you leave this field blank, you send the file to one of the following default locations:

  • In-Sight device: Root directory of the device
  • Emulator, In-Sight ViDi PC: C:/ProgramData/Cognex/In-Sight/In-Sight ViDi PC/pubfs
  • FTP server: The default directory of the specified FTP server

  • SFTP server: The root directory of the specified SFTP server
File Name

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

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

Specifies the file format of the image.

0 = BMP (default) Windows bitmap format (.bmp extension).
1 = JPEG Standard encoded JPEG format (.jpg extension).
2 = PNG Standard encoded PNG format (.png extension)
Max Append Value The maximum number of unique image files that can be written using the specified File Name.The minimum value is 0, the maximum is 9999999, the default value is 999. A counter increments 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 is 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 is overwritten by new files of the same name. If the value is set to -1 or an out of range value, then no counter is 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 is overwritten by new files with the same name.

0 = OFF (default) The counter continues to increment as each image is written out, up to the Max Append Value.
1 = ON The counter resets to 0.
Note: By default, the Reset checkbox is not selected. If you don't change the default setting, a button, labeled Reset is 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 is transferred.
1 = ON (default) Both image and an .svg file is transferred. When enabled, the .svg file containing the graphic overlay data is 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 uses 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 is not be an exact pixel-for-pixel match.
Enable File Cleanup

Enables or disables the cleanup functionality of the tool.

Note: This option is only available when the selected storage type is Local Device. When this setting is enabled, there is an additional 30-60 µs in processing time per tool execution for checking the free space on the vision system.
Minimum Free Space

Specifies the minimum percentage of the vision system storage that is to be kept as free space.

If the storage reaches the specified limit, the cleanup functionality starts cleaning up older files to ensure that the minimum free space is retained.
Desired Free Space

Specifies the desired percentage of the vision system storage that is to be kept as free space.

When the vision system storage reaches the minimum free space limit, and the cleanup functionality starts cleaning up older files, the cleanup process stops when the vision system storage reaches the desired free space.

Note: If the tool cannot delete enough files to reach the desired free space threshold, the function returns an error after deleting what it was able to delete. There is an additional 8 ms of approximated processing time for initiating cleanup, and an additional 0.8 ms for every file deleted.

WriteImage Outputs

Returns
  • A WriteImage data structure that writes the image data contained in the specified Image data structure to a local device or an FTP/SFTP 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 memory storage of the In-Sight D900 series vision system is full.
Note: Any invalid FTP/SFTP server path or file name does not return an #ERR.
Tip:

If you hover over an #ERR, the following error message is displayed:

Message Error Reason
#ERR: Cannot open file: file path/file name The specified File Path or File Name parameter is incorrect (that is, the file path is not created).
#ERR: Error 0:7:2: file path/file name The memory storage of the vision system 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, Reset buttons are 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 is either be zero, or blank filled. If the character immediately following a '|' is 0, the format is zero-filled; otherwise, it is blank filled. The next character(s) indicate how may 0 or ' ' to insert. If the filename contains multiple ‘|’ characters, the last one is used as the format indicator. If the ‘|’ character is not followed by a digit, then the ‘|’ is used as part of the name, following the restrictions of any operating system.

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

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

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

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