WriteImageSFTP

Writes the current image to an SFTP server on the network, communicating over the SSH protocol. Optionally, an SVG file may be created, which includes the overlay graphics on top of the image. This function is typically used to automatically save images of failed inspections during runtime.

Note:
  • This function cannot be used to transfer images to another In-Sight vision system or Emulator; a vision system may only serve as a client on a SFTP network.
  • The function requires the In-Sight vision system to be Online to send images and SVG files.
  • If you are logged on to an In-Sight vision system remotely, the screen image may not be refreshed with every image acquisition when using the function.
  • If a memory-intensive job containing the function is executed repeatedly, the FTP command "Get image.jpg" (or .bmp) may fail because the vision system's memory becomes too fragmented. The job will continue to execute correctly.
  • If an AcquireImage function parameter is modified while the vision system is Online, the function will send the current image.
  • Jobs containing this function that are saved in In-Sight Explorer 4.3.0 or higher are only compatible with In-Sight Explorer 4.3.0 and higher.
  • The port number of the FTP server connection can be changed by appending the host name (or IP address) with a colon (:) then the new port number. For example, if the current Host Name was PRODUCTION1, to change the port number from the default (port 21) to port 34, the Host Name parameter would be specified as PRODUCTION1:34.

  • The Emulator folder is located: C:\ProgramData\Cognex\In-Sight\Emulators\x.x.x (Windows 7/Windows 10). For more information, refer to the Emulation Panel.

  • If the default location of the saved images is kept as the Emulator folder, allowing more than 250 image files to be stored in the directory will prevent a firmware update of the vision system. Remove the image files from the directory to restore firmware update capability. For more information, see Update Firmware Dialog.

WriteImageSFTP Inputs

WriteImageSFTP(Event,Host Name,User Name,Password,Image,File Name,Max Append Value,Reset,Data Format,Save Graphic Overlays,Resolution,Disable SFTP Queuing)

Parameter Description

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. For more information, see AcquireImage.
  • A cell containing an Event function. For more information, see Event.
  • A cell containing a Button function. For more information, see Button.
Note: When the default Event reference is deleted, the value is replaced by a checkbox. If another cell is referenced as an event, the function will conditionally run based on the referenced cell. If the checkbox is enabled, the function will always run when any inputs to the function are updated.

Host Name

The host name (or IP address) of the target device on the network where the image file will be written. The target device can be an In-Sight emulator, or any other host acting as an FTP server on the network. An In-Sight vision system may only serve as a client on a SFTP network. The WriteImageSFTP function cannot be used to transfer images to another In-Sight vision system or Emulator.

Note:
  • If an invalid Host Name is specified, the connection may take up to 30 seconds to timeout.
  • When writing images to an FTP server, do not use spaces before or after the name specified in the Host Name or User Name. If the name specified in the Host Name or User Name parameters contains a space before or after the name, the function will fail to write the image to the specified server.

User Name

A valid user name for the target system's SFTP server. This user name is not required to exist on the In-Sight vision system that is writing the image file.

Password

A valid password for the target system's SFTP server. The password is case-sensitive, and its length cannot exceed 15 characters.

Note:
  • For security purposes, the entered password will be masked with "*" in the property sheet and in the formula bar.
  • The password will be saved in the job file in encrypted form.

Image

A reference to a cell containing an Image data structure. The default reference is to the Image data structure in cell A0.

File Name

The name of the image file to write; also defines the name of the SVG file, if the Save Graphic Overlays parameter is enabled. Long file names are supported, including a numeric counter that can be appended to the file name as each file is written (up to the specified Max Append Value). If no path is specified, the image file will be written to the default directory of the FTP server on the target host.

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 be added to the end of the specified File Name and will increment itself as each image file is written. 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.

The number of digits in the counter will be equal to the number of digits in the Max Append Value. For example, the default Max Append Value '999' will always cause 3 digits to be added to the FileName. If 0 is specified, then no counter will be appended to the File Name.

Reset

Restarts the counter that is appended to the specified File Name for both image and SVG files. Existing image files and SVG files on the target system will be overwritten by new files of 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.

Data Format

The file format of the image that will be written out to the target host.

0 = BMP (default)

Windows bitmap format (.BMP extension).

1 = JPEG

Standard encoded JPEG format (.JPG extension).

Save Graphic Overlays

Specifies whether an SVG file is created that contains overlay graphic data for supported In-Sight Vision Tools, Geometry Functions and Graphics Functions, when their Show parameter is set to display graphics. For more information, see Vision Tools Functions, Geometry Functions and Graphics Functions. The overlay graphics uses the formatting specified by the Format Cells dialog. For more information, see Format Cells Dialog.

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.

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 graphic data will not be an exact pixel-for-pixel match.
  • In-Sight firmware does not guarantee the transmission of every SVG and image file pair. If the In-Sight vision system is overloaded, it may skip the transmission of the SVG and/or image file to ensure that inspections and/or image acquisitions are not missed.

0 = OFF (default)

Specifies that only the image will be transferred.

1 = ON

Specifies that the 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, such as Microsoft Internet Explorer 9.0 or later, to view the graphic overlay data and images together.
Resolution

Specifies the image resolution at which the image will be exported.

1 = Full (default)

The image is exported at full resolution.

2 = Half

The image is exported at half resolution.
3 = Quarter

The image is exported at quarter resolution.
Disable SFTP Queuing

Specifies whether or not images should be queued prior to FTP transfer.

0 = Queue (default)

When this functionality is enabled, an attempt will be made to add the image to the FTP task queue every 5 milliseconds, up to 1,000 times, before dropping the image.

1 = Disable Queuing

When queuing is disabled, only one image from each instance of the function will be added to the FTP task queue at a time, otherwise the image will be dropped and no attempts will be made to re-send the image to the FTP task queue.

WriteImageSFTP Outputs

Returns
  • An SFTP data structure that will write the image data contained in the specified Image data structure to a file on the target system whenever the spreadsheet is updated.
  • Returns #ERR if the Host Name, User Name, or Password are invalid for the target host, if any input parameters are invalid or if the image queue is full. The image queue may contain one image at a time. If WriteImageFTP executes and tries to send an image before the previous image has been sent, the function will return an error.
Note:
  • If an image is queued, but the transfer to the target host failed, an #ERR is not returned.
  • Network errors that are generated by the function (such as invalid Host Name, User Name or Password) can be detected by inserting a separate Event function into the spreadsheet and specifying "Network Error" for the Trigger parameter. For more information, see WriteImageFTP and Event. These errors are then reported by the GetErrorString and GetErrorCode functions, which must reference the Event function. The last error message/code is stored and is returned until another network error is reported. For more information, see GetErrorString and GetErrorCode.

WriteImageSFTP Example

WriteImageSFTP($A$0,"SYSTEM1","admin","*",$A$0,"\IMAGES\TEST",999,0,0,0,1,0)

Whenever the spreadsheet updates after an image acquisition, this formula writes a bitmap image file across the network to the IMAGES directory located on the host named SYSTEM1. The user name admin, its password, and the IMAGES directory must already exist on SYSTEM1, or #ERR will be returned in the spreadsheet. The first file written would be TEST000.BMP, the second TEST001.BMP, and so on.

Note: A typical application would have the function be cell-state driven to save images only when a failed inspection occurs during runtime. For more information, see Cell State Dialog.