The compress_file and decompress_file user macros use the zlib compression library to compress and decompress data files respectively. When they are used in conjunction with other data IO modules they enable Express applications to read and write compressed data files.
| Name | Type | Description | |
| in_filename | String | Application defined file to be processed. | |
| Name | Type | Description | UI Control |
| filename | String | User defined file to be processed. | FileDialog |
| output_dir | String | Directory to write processed files to. | Text Box |
| remove_orig | int | whether the original file should be removed. | Toggle |
| Name | Type | Description | |
| out_filename | String | Name of processed file. | |
The compress_file and decompress_file user macros use the zlib compression library to compress and decompress data files respectively. The compress_file macro take a filename and a output directory as input and then compresses the specified file and writes the new compressed file to the output directory. Similarly the decompress_file macro decompresses the specified file and writes the new decompressed file to the output directory. Optionally the macros can also delete the original file. Internally the zlib compression library is used to perform the necessary compression and decompression. This library is compatible with the gzip compression schemes. Hence programs such as gzip and Winzip can also be used to read compressed files written by these macros.
These macros can be used on their own if simple, one-off, compression or decompression is required. Alternatively they can be used in conjunction with other Data Input or Output modules. This allows Express to easily read and write gzipped data files. The macro facilitate this by providing one input port and one output port. The in_filename port takes a filename to process as input. The out_filename port outputs the filename of the processed file.
Therefore to read a compressed data file you would take the out_filename port of a decompress_file macro and connect it to the filename input of a Data Input module. An example of this can be seen in the ReadCompressedImageEg application. Similarly to write a compressed data file you would take the filename output of a Data Output module and connect it to the in_filename port of a compress_file macro. An example of this can be seen in the WriteCompressedImageEg application.
The most important limitation of these macros is that they do not by default remove uncompressed files. This means that the user will be left with both compressed and uncompressed data files. When writing compressed data files this problem can be solved by using the remove_orig parameter. If this parameter is set the compress_file macro will automatically remove the original uncompressed data file. However this approach cannot be used when reading compressed data files. In this case removing the original file will remove the compressed file which will not normal be the desired behaviour. Due to this problem it is recommended that all uncompressed data files are written to a temporary directory so that they can be removed easily at a later date.
Recent versions of AVS/Express already contain the zlib library. It is part of the Animator Kit that was introduced with AVS/Express 4.0. By default the low-level code in this project is setup to use the zlib library this is contained in the Animator Kit. Normally the Animator Kit will be available and the installation and compilation of the ZipIO project can proceed as normal. However if the Animator Kit is disabled or not available the required code is not compiled into Express and hence an external copy of the zlib library will be required.
There are two steps that are required when compiling this project with an external copy of the zlib library. Firstly the library must be compiled and installed on your system. This may have already been. If it has not been done then the library can be obtained from http://www.zlib.net/ This web-site provides the library source code and pre-built libraries for a variety of platforms. It also provides links to pre-built libraries for many other platforms. Once you either obtained pre-built libraries or compiled libraries from the source code you should install the header files and library files in the appropriate include and lib directories.
The second step is to modify the project V code so that it knows that an external library is being used. This can be done by commenting or removing the following line in the zip_mods.v file:
#define ANIM_KIT_ENABLED
If the zlib library that you are using is called anything other libz.a on Unix or zlibdll.lib on Windows then you will also need to alter the name of the library that is linked into the express process. On Unix this can be done by altering the following line in the zip_mods.v file:
#define ZLIB_LINK_UNIX "-lz"
On Windows this can be done by altering the following line in the zip_mods.v file:
#define ZLIB_LINK_DOS "zlibdll.lib"
in_filename
String input that specifies which file should be processed. This input is intended to allow the filename string of other modules to be entered directly into the compress_file or decompress_file macros. If this input contains a valid string then this input will always be used instead of the filename parameter.
The compress_file macro will compress the file specified by this input and write the compressed file to the output directory after adding the .gz suffix to the filename. The decompress_file macro will decompress the file specified by this input and write the decompressed file to the output directory after removing the .gz suffix from the filename. If no .gz suffix is present then the file will not be decompressed.
filename
String parameter that specifies which file should be processed. This input is connected to the user interface and is intended to only be altered by the user. If the in_filename input contains a valid string then that input will be used instead and this parameter will always be ignored.
The compress_file macro will compress the file specified by this parameter and write the compressed file to the output directory after adding the .gz suffix to the filename. The decompress_file macro will decompress the file specified by this parameter and write the decompressed file to the output directory after removing the .gz suffix from the filename. If no .gz suffix is present then the file will not be decompressed.
output_dir
String parameter that specifies the directory that processed files should be written to. Often this will be a temporary directory but it can be any directory.
remove_orig
Integer parameter that specifies whether the original file specified by the in_filename input or filename parameter should be removed after it has been processed. If this parameter is set on the compress_file macro it can be used to remove the original uncompressed file once the compressed file has been written. The original file will only be deleted once the processed file has been written. However despite this some care should be taken when using this parameter as it will delete the original files automatically and without warning.
out_filename
String output that specifies the filename of the processed file. This input is intended to be connected to the filename string of other modules, hence allowing standard Data IO modules to automatically read compressed files. This output is only changed when the input file has been processed correctly.
The compress_file macro will output the name of the compressed file. Similarly the decompress_file macro will output the name of the decompressed file.
The User Macro compress_file combines the low-level module CompressFileCore with the UI Macro CompressFileUI. The User Macro decompress_file combines the low-level module DecompressFileCore with the UI Macro DecompressFileUI. These User macros also make use of the common parameter block ZipIOParams to tie the low-level module and UI macro together.
Two example applications are provided, WriteCompressedImageEg and ReadCompressedImageEg. The WriteCompressedImageEg application uses the OutputImage module to take a picture of the viewer window and write it to a AVS .x image. The application then uses the compress_file macro to compress this image and then delete the original uncompressed image file.
The ReadCompressedImageEg application uses the decompress_file macro to decompress the image written by the WriteCompressedImageEg application and then uses the Read_Image module to read the uncompressed image. Neither the compressed image or uncompressed image are deleted by this application.
All the filename and directory name inputs and parameters can contain AVS/Express environment variables (i.e. $XP_ROOT, $XP_PATH<1>). Separator characters will also be resolved correctly depending upon which platform is being used.
The low-level ZipIOMods library containing the low-level module BlankProjectCore does not specify a process. By default the express process will be used.
iac_proj/zip_io/zip_mods.v contains the V definitions of the CompressFileCore and DecompressFileCore modules and the ZipIOParams parameter block.
iac_proj/zip_io/zip_macs.v contains the V definitions of the CompressFileUI and DecompressFileUI UI macros and the compress_file and decompress_file user macros.
iac_proj/zip_io/zip_apps.v contains the V definitions of the WriteCompressedImageEg and ReadCompressedImageEg example applications.
Dr Federico Gamba, David Knight, AVS Inc. Lars Mueller, Manchester Visualization Centre Andrew Dodd, International AVS Centre
International AVS Centre Manchester Visualization Centre Manchester Computing University of Manchester Oxford Road Manchester United Kingdom M13 9PL