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 AcquireImage function's Trigger Mode is set to Continuous), it can cause 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 needs to be a reference to any event with a timestamp, for example AcquireImage 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/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.
Local Device	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 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 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 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/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 ~, 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 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.

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 (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 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 In-Sight D900 series vision system's memory storage is full.

Note: Any invalid FTP/SFTP 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: