WriteImageFTP

Writes the current image to an FTP server on the network. 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:
  • 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.

  • The image width is based on the width of the source image. The width will be adjusted, if needed, making it word-aligned (a multiple of 4). The width will be adjusted up to the next multiple of 4. If this new width is greater than the source image's width, the width will be adjusted down to the previous multiple of 4.

  • Jobs containing this function that are saved in In-Sight Explorer 3.3.0 or higher are only compatible with In-Sight Explorer 3.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.
  • 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.
  • When using the In-Sight emulator as an FTP Server, by default, files are written to the Emulator folder (C:\ProgramData\Cognex\In-Sight\Emulators\x.x.x). In addition to this directory, files can be written to a user-defined location (Authorized FTP directory). For more information on the Emulator directory and the Authorized FTP directory, see Emulation Panel.

WriteImageFTP Inputs

Syntax: WriteImageFTP(Event,Host Name,User Name,Password,Image,File Name,Max Append Value,Reset,Data Format,Save Graphic Overlays,Resolution,Disable FTP 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.

Note:
  • When the Host Name is set to an In-Sight emulator, the files are saved to: C:\ProgramData\Cognex\In-Sight\Emulators\5.x.x.
  • The Host Name drop-down does not list Host Names of In-Sight vision systems and/or emulators on the network. Manually enter the host name or the IP address of the target vision system/emulator in the Host Name field.
  • 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 FTP 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 FTP 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.

Note: When writing files to the Authorized FTP Directory, the File Name path must precisely match the specified Authorized FTP Directory path in the Options dialog. Images can also be written to any sub-directories within the Authorized FTP Directory (the sub-directory must exist). For example, if the Authorized FTP Directory is C:\temp and the name of the file is "Failed", the File Name must be specified as "c:\temp\Failed". If writing to a sub-directory "Images", the File Name will be "C:\temp\Images\Failed". If only specified as "Failed", the file will be written to the default Emulator directory.

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.
  • When using In-Sight firmware 5.6.0 or later and the function's Host Name parameter is set to an In-Sight emulator, the SVG files are saved to the emulator directory (C:\ProgramData\Cognex\In-Sight\Emulators\5.x.x) and displayed in the In-Sight Files pane. For more information, see In-Sight Files
  • When using In-Sight firmware 5.5.x or earlier and the function's Host Name is set to an In-Sight emulator, the SVG files are saved to the emulator directory but will not be displayed in the In-Sight Files pane.

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 FTP 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.

WriteImageFTP Outputs

Returns
  • An FTP 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.

WriteImageFTP Example

WriteImageFTP($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.