NAME

viz.pl - server-cache web vizualization interface


SYNOPSIS

  require "viz.pl";

  # Most common methods shown here.  See METHODS for others.

  $img = viz_get_fullsize($file->{oid}, $file->{location});
  print "<IMG SRC=\'$img\'>";

  $thumb = viz_get_thumbnail($file->{oid}, $file->{location});
  print "<IMG SRC=\'$thumb\'>";

  $copy = viz_make_copy($file->{location});
  print "<A HRF=\'$copy'> copy of file </A>";

  viz_convert("foo.tiff", "foo.jpg");   # converts foo to jpg.


REQUIRES

Image::Magick, wrm.pl


DESCRIPTION

viz.pl is a visualization interface that provides image conversion facilities and web-accessibility to WRM files. It is used by the gateway interface (gateway.pl) to provide html access to WRM files. The CGI programmer should use gateway.pl and not the functions in viz.pl directly.

Files managed by WIRM can reside in the File Storage Area or in other locations accessible by the WRM server. These locations are not necessarily accessible from the web, however. The Viz API (viz.pl) provides web access to files managed by WRM by maintaining a web-accessible cache (called the ``vizcache'') on the server. When a user requests a file through a WRM-created web page, the repo API uses viz.pl to copy the file into the vizcache (or if it already exists in the vizcache, the existing copy is used). Furthermore, if the file is a recognized image type, it is converted into a jpeg for web-viewing before being copied.

viz.pl uses Image::Magick to perform its image manipulation. Image::Magick recognizes a wide range of image types, although users may extend the set of image types by implementing their own conversion routines, such as we have done with the GE MRI format. These extensions must be incorporated into the viz_convert function.

In addition to providing fullsize jpeg replicas of images, viz.pl also provides functions for generating thumbnail versions.

Currently, the vizcache consists of 3 parititons: one for thumbnails, one for fullsize jpegs, and one for other file types. The vizcache location is specified in the CONFIG file ($WRM_CONF{repo_viz}).

The location of a file in the vizcache is determined by the file ID (using a hash function), so that must be supplied when using the viz_get functions to request a file. Helper functions such as viz_fullsize_dir() compute the location. In addition, the virtual path can be computed with the vdir() functions (virtual paths are rooted at the hypertext document root).


METHODS

viz_get_fullsize($id, $source)
Returns virtual path filename of fullsize jpeg version of specified $source file in web-viewable image cache. If the jpeg version does not yet exist, creates it using viz_make_fullsize(). $id parameter required for locating the converted file. $source must be a recognized image type (either recognized by Image:Magick or one of the user-defined image types supported by this API).

viz_get_thumbnail($id, $source)
Returns virtual path filename of jpeg thumbnail of specified $source file in web-viewable image cache. If the thumbnail does not yet exist, creates it using viz_make_thumbnail(). Size of thumbnail determined by global variables $THUMB_W and $THUMB_H. $id parameter required for locating the converted file. $source must be a recognized image type (either recognized by Image:Magick or one of the user-defined image types supported by this API).

viz_make_copy($source)
Copies $source into web-accessible vizcache ``other'' area. Returns virtual path filename of copy. If a copy exisits in the vizcache with the same name, it will be overwritten. Note that unlike thumbnail and fullsize areas, the ``other'' area does not maintain hashed locations based on file id.

viz_convert($source, $dest, $width, $height)
Converts $source file to $dest file. $source must be a recognized image type (see Image::Magick for types; also handles MR type). The extension of the $dest filename will determine the desired type to convert to. The converted file will be written to $dest. Optional $width and $height (in pixels) can be used to scale the result.

viz_mr_convert($source, $dest, $width, $height)
Converts $source file to $dest file. $source must be of type MR (GE Magnetic Resonance Image slice). The extension of the $dest filename will determine the desired type to convert to. The converted file will be written to $dest. Optional $width and $height (in pixels) can be used to scale the result.

viz_make_fullsize($id, $source)
Creates a fullsize jpeg version of specified $source file in web-viewable image cache using viz_convert(). Does not check to see if file already exists in cache (user should consider viz_get_fullsize to avoid overhead of converting files that already exist in cache). Returns virtual path name of resulting file. Directories along path will be created if they don't yet exist. $id parameter required for locating the converted file. $source must be a recognized image type (either recognized by Image:Magick or one of the user-defined image types supported by this API).

viz_make_thumbnail($id, $source)
Creates a jpeg thumbnail of specified $source file in web-viewable image cache using viz_convert(). Does not check to see if file already exists in cache (user should consider viz_get_thumbnail to avoid overhead of converting files that already exist in cache). Returns virtual path name of resulting file. Directories along path will be created if they don't yet exist. $id parameter required for locating the converted file. $source must be a recognized image type (either recognized by Image:Magick or one of the user-defined image types supported by this API).

viz_fullsize_dir($id)
Returns the real location (not including filename) of the web-accessible cached fullsize version of file specified by $id.

viz_fullsize_vdir($id)
Returns the virtual location (not including filename) of the web-accessible cached fullsize version of file specified by $id.

viz_thumbnail_dir($id)
Returns the real location (not including filename) of the web-accessible cached thumbnail version of file specified by $id.

viz_thumbnail_vdir($id)
Returns the virtual location (not including filename) of the web-accessible cached thumbnail version of file specified by $id.

viz_bucket($id)
Returns destination bucket number using hash function on supplied file $id.


AUTHOR

Rex Jakobovits, rex@cs.washington.edu


SEE ALSO

gateway.pl, Image::Magick