This page documents extended file formats used by Visustin. It is intended for developers planning to programmatically read the image files created by Visustin, or to save images to open them with Visustin.
Visustin supports extended GIF, PNG and TIFF image file formats. The extended file formats store metadata about the flow chart images. The stored information includes flow chart title, creation date and flow chart metrics.
Source code could optionally be saved in .code.gif, .code.png and .code.tif files by Visustin v4–v6. Starting with Visustin v7.0, this is no longer possible. Existing files can still be read. The specifications marked with † are considered legacy starting with Visustin v7.0.
A Visustin Editor flow chart could optionally be embedded in .flw.png files by Visustin v5–v7. Starting with Visustin v8.0, this is no longer possible. Existing files can still be read. The specifications marked with †† are considered legacy starting with Visustin v7.0.
| Format | Image only | Image+code † | Editable image | Number of images |
|---|---|---|---|---|
| Extended PNG | .png | .code.png † | .flw.png †† | 1 |
| Extended GIF | .gif | .code.gif † | 1 (or many †††) | |
| Extended TIFF | .tif | .code.tif † | 1 or many |
† Legacy format starting with Visustin v7. †† Legacy format starting with Visustin v8. ††† Visustin v4–v5 allowed saving of several images into a single .gif file.
The extended file formats are fully standards compatible. Other applications will read and display the images, but not the extra data in them.
Privacy note: The .code.* files contain source code. Do not distribute them if you do not wish to share the code.
The following is a detailed technical description of the Visustin extended PNG, GIF and TIFF file formats. It is intended for developers planning to programmatically read the image files created by Visustin, or to save images to open them with Visustin.
.png, .code.png and .flw.png
Visustin extends the PNG file format by using the PNG standard "text chunk" mechanism to store information about the flow chart image. The extension was defined by Visustin v4.0 and extended by Visustin v5.0.
Text chunks are a standard way to store textual information about the PNG image. Visustin uses 4 standard keywords and some extended Visustin-specific keywords. Applications not supporting these keywords will simply ignore them, making the extension compatible with all standards compliant PNG applications.
| Standard keyword | Description | Chunk saved |
|---|---|---|
| Title | Title of image | tEXt/iTXt |
| Description | Description of image | tEXt/iTXt |
| Software | Software used to create the image | tEXt |
| Creation Time | Date saved | tEXt |
| Extended keyword | Description | Chunk saved |
| SourceCodeLanguage | Language of source code (see language codes) | tEXt |
| CyclomaticComplexity | McCabe cyclomatic complexity number V(G). | tEXt |
| Links | Total number of links (graph edge count). | tEXt |
| Shapes | Total number of graph shapes (graph node count). | tEXt |
| SourceCodeLines | Number of physical source code lines the graph was created from. | tEXt |
| Extended keyword (.code.png) | Description | Chunk saved |
| SourceCode † | Source code from which the image was created | tEXt/iTXt |
| SourceCodeCharset † | Windows character set for the display of SourceCode (integer 0-255) | tEXt |
| SourceCodeFile † | Path and file name of source code file the image was created from, if known | tEXt/iTXt |
| SourceCodeDate † | Date the source code was last modified, if known | tEXt |
† Legacy field, saved in .code.png files only (Visustin v4–v6).
Visustin Editor only saves Description, Software and Creation Time.
Text chunks. Visustin saves uncompressed tEXt (plain text) and iTXt (international text) chunks. A regular tEXt chunk is saved when it is possible to represent the text in the ISO-Latin-1 character set (ISO 8859-1). An iTXt chunk is saved when the text contains other characters. When loading a PNG file, tEXt and iTXt chunks are accepted equally.
Dates are stored in the RFC 1123 date format (d mon yyyy hh:mm:ss zzz) using the local time zone. Example: 18 Sep 2006 12:34:56 +0300.
Metrics CyclomaticComplexity, Links, Shapes and SourceCodeLines are stored as non-negative integer values. A missing field indicates a missing value. Metrics details
d mon yyyy). Newer versions save date and time. That is backwards incompatible with Visustin v4.†† Legacy block used in .flw.png files only (Visustin v5–v7)
To store flow chart editor information (for Visustin Editor), Visustin stored a private flOw chunk in a PNG file. The string "flOw" (66h 6Ch 4Fh 77h) indicates a private non-critical safe-to-copy chunk type in PNG. The following table describes the flOw Chunk Data.
| Field | Bytes | Contents | Description |
|---|---|---|---|
| Identifier | 8 | "FLOWEDIT" | 8 ASCII characters. |
| Application Authentication Code | 3 | 01h x x | Version and checksum (see authentication code) |
| Data bytes | |||
| ImageCRC | 4 | 32-bit integer | CRC-32 of IDAT chunks when FLOWEDIT block was saved. ImageCRC is calculated exactly the same way as chunk CRC-32 in PNG, but this checksum is calculated over all IDAT chunks, not just one chunk. If ImageCRC differs from CRC-32 of IDAT chunks, the image was modified after the flow chart data was saved. If only one IDAT chunk exists, ImageCRC equals its CRC field. |
| Flags | 1 | Bit flags | Bit 0: 0 = ImageCRC not set, 1 = ImageCRC is set. Other bits are reserved, set to zero. |
| Compression | 1 | Unsigned Byte | Compression of field FCData. 0 = uncompressed 1 = zlib compressed (inflate/deflate, the same method as used in PNG elsewhere) other = reserved, incompatible |
| FCMajor | 1 | Unsigned Byte | Flow chart compatibility version (5). |
| FCMinor | 1 | Unsigned Byte | Flow chart sub-version (1). |
| FCLength | 4 | 32-bit integer | FCData field size (number of bytes). Acceptable values: 0 to 231-1. |
| FCLengthUnc | 4 | 32-bit integer | FCData field size when uncompressed (number of bytes). Equals FCLength if no compression is used. Acceptable values: 0 to 231-1. |
| FCData | <FCLength> | binary data | Flow chart data in Lassalle AddFlow.ocx v5.4 .flw file format, either uncompressed or zlib compressed. |
FCMajor.FCMinor
5.0 = Visustin v5.0 flow chart.
5.1 = Visustin v6.x flow chart.
5.2 = Visustin v7.x flow chart.
5.x = Visustin v5.0/v6.x/v7.x compatible flow chart.
Any other: Not compatible with Visustin v5.0/v6.x/v7.x.
Byte order. All data in the flOw chunk is in Intel byte order, even though the rest of the PNG file is in network byte order.
flOw chunk size is 11+16+FCLength bytes at a minimum. Read applications must discard bytes after the FCData field to allow for possible future expansion of the data format.
An imaging application that changes the PNG file can leave the flOw block intact without affecting the contents of the data. In this case, however, the flow chart may not resemble the image any more. The ImageCRC field can be used to detect this change.
Visustin extends the GIF file format by using the GIF89a standard "application extension block" mechanism to store extra information about the flow chart image(s).
Application extension blocks are a standard way to add extra information into GIF89a files. Visustin defines 2 application extension blocks with information about flow charts and source code. Applications not supporting these blocks will simply skip over them, making the extension downward compatible with existing applications. The extension blocks were defined by Visustin v4.0 and extended by Visustin v5.0 and v6.0.
.gif and .code.gif
A FLOWIMG block stores information about the flow chart image. This block is optional. When present in the GIF file, it applies to the image (<Graphic Block>) that follows next. A GIF file can contain any number of FLOWIMG blocks, but a maximum of one per each image. Visustin saves FLOWIMG blocks in both .gif and .code.gif files.
| Field | Bytes | Contents | Description |
|---|---|---|---|
| Introducer | 1 | 21h | Extension Introducer |
| Label | 1 | FFh | Application Extension Label |
| Size | 1 | 0Bh | Block Size (11 bytes) |
| Application Identifier | 8 | "FLOWIMG " | 8 characters, last character is a space. |
| Application Authentication Code | 3 | 03h x x | Version and checksum (see authentication code) |
| Data sub-blocks | One or more GIF data sub-blocks containing the following fields | ||
| Creation Date | 4 | 32-bit integer | Date the image was created. Stored as the number of days passed since 1899-12-30. Zero if unknown. Negative value is error. |
| Title | n | Zero-terminated UTF-8 string | Title of image. Zero-length string if unknown. |
| SourceCodeLanguage | n | Zero-terminated UTF-8 string | Language of source code (see language codes) |
| Creation Time | 4 | packed, see below | Time of day the image was created. Specific format, see below. |
| CyclomaticComplexity | 4 | 32-bit integer | McCabe cyclomatic complexity number V(G). Negative if unknown. |
| Links | 4 | 32-bit integer | Total number of links (graph edge count). Negative if unknown. |
| Shapes | 4 | 32-bit integer | Total number of graph shapes (graph node count). Negative if unknown. |
| SourceCodeLines | 4 | 32-bit integer | Number of physical source code lines the graph was created from. Negative if unknown. |
| Software | n | Zero-terminated UTF-8 string | Software used to create the image. |
| ChartType | 1 | Byte | 0=unknown 1=flow chart 2=UML Activity Diagram |
Change note. Version 01h format (Visustin v4) included fields up to SourceCodeLanguage. Version 02h format (Visustin v5) included 5 new fields: CreationTime, CyclomaticComplexity, Links, Shapes, SourceCodeLines. Version 03h format (Visustin v6–) includes 2 new fields: Software and ChartType.
† Legacy block used in .code.gif files only (Visustin v4–v6)
A FLOWSRC block stores information about the source code of the flow chart. This block is optional. When present in the GIF file, it applies to the image (<Graphic Block>) that follows next. A GIF file can contain any number of FLOWSRC blocks, but a maximum of one per each image. Visustin saves FLOWSRC blocks in .code.gif files but not regular .gif files.
| Field | Bytes | Contents | Description |
|---|---|---|---|
| Introducer | 1 | 21h | Extension Introducer |
| Label | 1 | FFh | Application Extension Label |
| Size | 1 | 0Bh | Block Size (11 bytes) |
| Application Identifier | 8 | "FLOWSRC " | 8 characters, last character is a space. |
| Application Authentication Code | 3 | 02h x x | Version and checksum (see authentication code) |
| Data sub-blocks | One or more GIF data sub-blocks containing the following fields | ||
| SourceCodeDate | 4 | 32-bit integer | Date the source code was last modified. Stored as the number of days passed since 1899-12-30. Zero if unknown. Negative value is error. |
| SourceCodeFile | n | Zero-terminated UTF-8 string | Path and file name of source code file the image was created from. Zero-length string if unknown. |
| SourceCode | n | Zero-terminated UTF-8 string | Source code from which the image was created |
| SourceCodeTime | 4 | packed, see below | Time of day the source code was last modified. Specific format, see below. |
| SourceCodeCharset | 1 | Byte | Windows character set for the display of SourceCode. 1 if unknown. |
Change note. Version 01h format (Visustin v4) included fields up to SourceCode. Version 02h format (Visustin v5–v6) also included fields SourceCodeTime and SourceCodeCharset.
Date fields express days passed since 1899-12-30, relative to local time. A zero value indicates unknown date. Dates are stored as a positive 32-bit long integer. The acceptable range is 1..2958465, which express dates 1899-12-31 until 9999-12-31. Other values should be treated as unknown date.
Time fields represent local time with optional time zone packed in a 32-bit integer:
| Bits | 31..30 | 29 | 28 | 27..17 | 16..0 |
|---|---|---|---|---|---|
| Field | Reserved | Validity | Time zone direction | Time zone | Local time |
| Contents | 0 | 1 = time is given 0 = time not given |
1 = ahead of UTC (+) 0 = behind UTC (-) |
Difference to UTC in minutes 0..1440 |
Seconds since midnight 0..86400 |
| Data format | - | Bit flag | Bit flag | Unsigned 11-bit integer | Unsigned 17-bit integer |
The time zone is expressed as difference in minutes to UTC. As an example, +0 = UTC, +60=UTC+1 hour, +840=UTC+14 hours. -0 represents undefined time zone, used for storing local time only. An unknown time is represented by setting all bits (31..0) to zero.
Text fields are stored as variable-length zero-terminated UTF-8 strings. A zero-length text field (containing only the zero-terminator byte) indicates unknown data.
Extension. Reader applications should ignore any data that follows the last field of the block. This is reserved for possible future extension of the format.
.tif and .code.tif
Visustin extends the TIFF file format to include flow chart information inside the TIFF file.
Private tags are a standard way to extra information to TIFF 6.0 files. Applications not supporting a private tag will skip over it, making the extension compatible with existing applications. The private TIFF tag 50951 Flow chart information can exist for each image in the TIFF file. The tag points to a private Image File Directory (IFD) within the TIFF file. This extension has been defined by Visustin v5.0 and extended by Visustin v6.0.
| Tag | = 50951 (C707.H) |
| Type | = LONG |
| Count | = 1 |
| Value | = Offset in TIFF file |
| Default | = Undefined |
The tag is a pointer to a private FlowIFD. This is a private IFD having the same structure as that of the IFD specified in TIFF, but it contains private tags only. FlowIFD contains flow chart related information about the image (page) in question. In a multi-page TIFF, each FlowIFD applies to a single page only. Tags CopySource and CopyTags can extend FlowIFD data to multiple images. FlowIFD is optional; an image might not have it.
| TagName | Decimal | Type | Count | Description |
|---|---|---|---|---|
| ChartType | 1 | BYTE | 1 | 0=unknown 1=flow chart 2=UML Activity Diagram |
| SourceCode † | 2 | UTF-8 | n | Source code from which the image was created |
| SourceCodeCharset † | 3 | BYTE | 1 | Windows character set for the display of SourceCode (0-255) |
| SourceCodeDate † | 4 | ASCIIZ | 20 | Local date and time the source code was last modified. The format is "YYYY:MM:DD HH:MM:SS", the same as TIFF field DateTime. |
| SourceCodeFile † | 5 | UTF-8 | n | Path and file name of source code file the image was created from, if known |
| SourceCodeLanguage | 6 | UTF-8 | n | Language of source code (see language codes) |
| Title | 7 | UTF-8 | n | Title of image |
| CopySource † | 8 | LONG | 1 | Source image (page) to copy FlowIFD tags from. 0-based index. |
| CopyTags † | 9 | SHORT | n | Array of FlowIFD tags to copy from source image. |
| Metric tags | ||||
| CyclomaticComplexity | 101 | LONG | 1 | McCabe cyclomatic complexity number V(G) |
| Links | 102 | LONG | 1 | Total number of links (graph edge count) |
| Shapes | 103 | LONG | 1 | Total number of shapes (graph node count) |
| SourceCodeLines | 104 | LONG | 1 | Number of physical source code lines |
† Legacy field included in .code.tif files only (Visustin v5–v6).
Change note: Visustin v6 added fields CopySource and CopyTags.
Type. This is the data type of the tag as defined on page 15 of the TIFF 6.0 specification. An additional data type is defined as follows:
| 65001=UTF-8 | UTF-8 encoded text. The last byte must be NUL (binary zero). The value of the Count field equals the number of bytes required to store the text, including the NUL, but excluding the pad byte, if any. Each UTF-8 field contains exactly one string. |
Default value. If a tag is missing, its value is unknown. If the Title tag is missing, the tag ImageDescription (270) or another tag may be used instead.
The legacy CopySource and CopyTags indicate that FlowIFD tags from another image (in the same file) apply to this image. CopySource is a 0-based image number identifying the source image. The FlowIFD tags of the source image apply to this image if they are listed in the CopyTags array. Restriction: Source image may not define its own CopySource for the same tags (no chained copy). The CopySource-CopyTags mechanism was primarily designed for .code.tif related tags marked with †. If SourceCode is copied, its meaning changes from "Source code from which the image was created" to "Source code from which these images were created".
All other tag numbers are reserved for future extension of the format. As required in TIFF, all data can be in either II or MM byte order.
TIFF 6.0 specification: TIFF Revision 6.0. Final - June 3, 1992. Adobe Developers Association.
The 3-byte Application Authentication Code field contains a binary code that verifies the structure of the block.
| Field | Bytes | Data type | Description |
|---|---|---|---|
| Version | 1 | unsigned byte | Version number of block format. |
| Checksum | 2 | unsigned 16-bit integer | CRC-16-IBM checksum of the data (sub-block) bytes. |
Version contains the block format version number. Version numbers 1..64 will be compatible with readers built using this specification. Version numbers 65..255 should be treated as incompatible and a reader application should not try to interpret the block.
Checksum is calculated from the data bytes immediately following the Checksum field until the end of the data block (FLOWIMG, FLOWSRC, FLOEDIT). In the GIF file format, the data bytes are the actual content bytes of the data sub-blocks. Data sub-block size bytes, part of the GIF89a specification, are not used as input. The checksum algorithm is CRC-16-IBM (BISYNCH). The CRC input data consists of the entire contents of the data sub-blocks. For future expansion of the block format, all the data bytes are used as input, not regarding the actual number data fields defined in this specification. That is, the data bytes possibly following the currently defined data fields are counted in the CRC as well. This ensures downward compatibility of future extensions. The CRC algorithm parameters (according to the Rocksoft™ Model CRC Algorithm) are: Width: 16, Poly: 8005, Init: 0000, RefIn: True, RefOut: True, XorOut: 0000, Check: BB3D. If there is a checksum mismatch, a reader application should assume that the block is invalid.
The SourceCodeLanguage field (PNG, GIF, TIFF) contains an abbreviated language code denoting the original programming language of the source code. The language codes are the same as the ones Visustin accepts as the /Lang command line parameter. COBFIX means fixed COBOL code, for example.
List of language codes. Notice that the slash "/" is not part of a language code. As an example, PERL is the language code for the Perl language, while /PERL is the respective command line switch.
The following table defines the various metrics stored in the PNG, GIF and TIFF files.
| Field | Data type | Range | Description |
|---|---|---|---|
| CyclomaticComplexity | 32-bit signed integer | 1..231−1 | McCabe cyclomatic complexity number V(G). |
| Links | 32-bit signed integer | 0..231−1 | Total number of links (graph edge count). All links are included, even those that do not look like an arrow. |
| Shapes | 32-bit signed integer | 0..231−1 | Total number of graph shapes (graph node count). There is an invisible shape at the start of a flow chart. |
| SourceCodeLines | 32-bit signed integer | 0..231−1 | Number of physical source code lines the graph was created from. This line count includes all lines, be it code, comment or blank. A line ends at a newline character. Line continuation characters are not taken into account. |
For detailed information, see Metrics.