class ref name: imagefile
category-group: files
layer: 10
header file: z_imagefile.h

synopsis.
The imagefile object (imagefile_o) represents a file whose contents is that of an image. There are several types of image files. They are customarily indicated by these standard file extensions:

  • gif - Graphics Interchange Format
  • jpg - "Joint Photographic experts Group"
  • bmp - BitMaP
  • png - Portable Network Graphics
There are many other image file formats: tiff, img, pcd, pic, psd, pgm, ras, dib, pcx, and many others. Only the ones above are supported by the Z Directory object imagefile_o. "jpg" has different flavors (varieties of jpg) and sometimes the file extension "jpeg" is used instead of "jpg".

The image file class exists mainly to get picture information from an image file, such as width and height in pixels, or image format type.

description.
A set of cardinal (integer) code values are used to represent types of images. They are implemented as macros, and act as enums. These values are found in z_imagefile.h and are as follows:

name value file extension description
zt_Image_JPG 1 jpg .jpeg or .jpg
zt_Image_PNG 2 png portable network graphics
zt_Image_GIF 3 gif graphics interchange format
zt_Image_TIFF 4 tiff tagged image file format
zt_Image_BMP 5 bmp Microsoft bitmap format
zt_Image_ICO 6 ico Microsoft icon format
zt_Image_WEBP 7 webp Google WebP format; a type of .riff
zt_Invalid_Image -1 [N.A.] indicates the image type is not set or invalid

member functions (primary)

imagefile_o()
SIGNATURE: imagefile_o ()
SYNOPSIS: creates a a new file object, completely devoid of name, path, or any internal information.
 

imagefile_o(imagefile_o)
SIGNATURE: imagefile_o (const imagefile_o &rhs)
SYNOPSIS:
creates a a new image file object, based on the file represented by file object "rhs". The file's address will be copied. No actual file on a computer file system is created - only a c++ object is instantiated.
 

operator = (imagefile_o)
SIGNATURE: const imagefile_o &operator = (const imagefile_o &rhs)
SYNOPSIS:
The current image file object is set to that of 'rhs'. This is not a "deep copy" operation, as the file object is made to simply point to whatever 'rhs' is pointing to (if anything). The resuls is that the current file object will have a file address that is equal to that of 'rhs' (they will point to the same file).
To copy the file who's file name is provided by the variable 'rhs', use one of the "deep copy" functions, such as copy_contents() , copy_from() , or copy_to() .
 

destructor
SIGNATURE: ~imagefile_o ()
SYNOPSIS:
destroys the class object instance. No actual file on any computer file system is removed. Only the object in the program is destroyed.
 

imagefile_o(<args>)
SIGNATURE: imagefile_o (const string_o &s)
SYNOPSIS:
similar to the "file_o (const string_o &s)" constructor. This creates a new imagefile object and sets the address to that specified in parameter 's'.
TRAITS: this function is inline.
 

imagefile_o(<args>)
SIGNATURE: imagefile_o (const file_address_o &f)
SYNOPSIS:
similar to "file_o (const file_o &f)" constructor. This creates a new imagefile object and sets the address to that specified in "f" (which should be set).
 

width()
SIGNATURE: size_t width (int *pi = NULL)
SYNOPSIS:
provides the width of the image, in pixels. If the file is not an image file, 'pi' (if a non-NULL variablle is provided) will be set to non-zero.
 

height()
SIGNATURE: size_t height (int *pi = NULL)
SYNOPSIS:
provides the height of the image, in pixels. If the file is not an image file, 'pi' (if a non-NULL variablle is provided) will be set to non-zero.
 

size()
SIGNATURE: size_t size (int *pi = NULL) const
SYNOPSIS: computes the width and height of an image in a file. The results are saved in the internal variables 'my_x' and 'my_y'.
DESCRIPTION: This calls the member function sync(), which in turn calls dimensions().
 

dimensions()
SIGNATURE: int dimensions (size_t &w, size_t &h, boolean force = FALSE, int *pi = NULL)
DESCRIPTION:
This member function "syncs" the object's internal variables with the contents of the file if parameter 'force' is TRUE. this function is logicallly similar to width_and_height(), but stores the results into the object's internal variables.
 

width_and_height()
SIGNATURE: int width_and_height (size_t &w, size_t &h, int *pi = NULL)
SYNOPSIS:
compute the width and height of an image in a file and return the results in output parameters 'w' and 'h' (No internal variables are affected by this call).
 

type()
SIGNATURE: int type (const boolean force = FALSE, int *pi = NULL)
SYNOPSIS: the Z Directory image type code (see the list in the main-line discussion, below).
PARAMETERS

  • force - if TRUE, the file will be examined, irregardless of whether the file was examined earlier and whether the image information was stored into the internal variables of the object. If FALSE, and the file was examined earlier, the settings found in the internal variables will be used to determine the file's image type.
  • pi - [output] error indicator variable. values:
    0: success
    zErr_Resource_Missing: file not found
    zErr_OperationIncomplete: file size could not be determined (this error occurs only inside the call to dimensions())
DESCRIPTION:
this member function uses z_imagefile_type() to determine the image type. The file name extension is completely ignored.
 

type_to_str()
SIGNATURE: string_o type_to_str (int *pi) const
SYNOPSIS:
returns a string containing the text code for the [Z Directory] image code of a file. The string is the same as the default file extension string (in lower-case).
DESCRIPTION:
This member function is similar to z_imagefile_code_to_extension(), but is intended to be applied to actual, existing image files. It is simply a convenient wrapper around these two member function calls:

  • z_imagefile_type()
  • z_imagefile_code_to_extension()
See the table in the main-line discussion for a list of these values.
 

is_ok()
SIGNATURE: boolean is_ok () const
SYNOPSIS: returns TRUE if a file sync was done, and was fully successful ('my_dimsok' set to TRUE).
 

is_synced()
SIGNATURE: boolean is_synced (int *pi = NULL) const
SYNOPSIS: returns the value of 'was_synced'.
PARAMETERS

  • pi - [output] error indicator variable. values:
    0: success
    zErr_OperationAborted: sync() was done, but 'my_dimsok' is set to FALSE, indicating a problem in the syncing.
    • DESCRIPTION:
    this tells if a sync() call was done prior by the object. it does not give the complete picture, in that it does not tell if sync() was successful (use is_ok() for that).
     

    reset()
    SIGNATURE: int reset()
    SYNOPSIS:
    returns all values in the object to at-[default]-construction state. All internal variable values are wiped out. However, file_o::reset() is not invoked. Thus, any file name is preserved.
     

    sync()
    SIGNATURE: int sync (int *pi = NULL)
    SYNOPSIS:
    syncs the object with its underlying file. Successful usage of this member function requires setting the file name to a valid, accessible, existing file.
    DESCRIPTION:
    This calls the member function dimensions(). The variables will always be recomputed when calling this function.
     

    resize()
    SIGNATURE: int resize (paramstring_o &ps, int *pi)
    SYNOPSIS:
    resizes the image file. the old contents is over-written. resizing can be done as a simple percentage, resizing the width, the height, or fixed width and height.
    DESCRIPTION:
    due to the numerous variations in how to resize, the parameter string object is used to hold the specifications (thus, this is reminiscent of symbolic programming). Specify a keyword followed by values, like so: 

      imagefile_o dif("veronica.jpg");
  string_o s;
  s = "HOW=FIXEDWIDTH x=400";   // resize to a width of 400px
  s = "HOW=PERCENT amount=50";  // resize to half-size
  s = "HOW=FIXED_DIMS x=150 height=200";
  paramstring_o ps(s);
  int ie0 = dif.resize(ps);
  if (!ie0) std::cout << "image resizing succeeded.\n";
    There are a number of keywords that are equivalent:
    • FIXEDWIDTH, FIXED_WIDTH, WIDTH - set the image to a specific width
    • FIXEDHEIGHT, FIXED_HEIGHT, HEIGHT - set the image to a specific height (in pixels)
    • FIXED_DIMS, WIDTHxHEIGHT - set the image to fixed x and y dimensions
    • x, w, width: the image width
    • y, h, height: the image height

     

    z_imagefile_fix_badextension()
    SIGNATURE: int z_imagefile_fix_badextension (file_o &, int *pi = NULL)
    SYNOPSIS: This subroutine checks the file's extension and compares it to the image file type, as determined by the contents of the file.
    DESCRIPTION:
    Usage of this member function is legitimate only when the file name is set so that it points to an actual image file. If the file's extension is different from that indicated by the file contents, the file is renamed so that the extension matches.
    TRAITS: this is a global-scope function (not a class member function)
     

    z_imagefile_type()
    SIGNATURE: int z_imagefile_type (const file_o &f, boolean strict = FALSE, int *pi = NULL)
    SYNOPSIS:
    gets the image type from the file contents. This is really a convenience function built around a call to z_imagetype_magicheader(). It reads the first 64 bytes of the file into a binary-mode string object, then examines the contents to determine the image type.
    TRAITS: this is a global-scope function (not a class member function)
     

    z_imagetype_magicheader()
    SIGNATURE: int z_imagetype_magicheader(const byte_t *data, size_t nb, boolean = FALSE)
    SYNOPSIS:
    this function examines the contents of 'data' in order to determine what type of image it contains. This function is used by member functions of imagefile_o.
    PARAMETERS

    • data - a pointer to a block of bytes. The contents of this block is intended to be the first [n] bytes of an image file (typically n = 64).
    • nb - the length of 'data'
    • strict - use more intense, maximum checking to confirm the file type. This currently is used only for jpg type images.
    DESCRIPTION:
    this function is independent of any file operations. It is typically applied to the contents of a file, but can be used on any data block of type 'byte_t'.
    TRAITS: this is a global-scope function (not a class member function)
     

    z_lookslike_imagefile()
    SIGNATURE: boolean z_lookslike_imagefile (const file_o &f)
    SYNOPSIS: this examines the file extension of 'f' to determine whether or not the file is an image file.
    DESCRIPTION:
    This member function does not guarantee that the result is genuine. That is, a file may have an image file extension (eg, ".jpg", or ".bmp") but be something entirely different. In this case, the file extension spoofs an image file. Also, the file need not actually exist - only the file name of the object ('f') needs to be set.
    Use z_imagefile_type() to do actual image file type verification.
    TRAITS: this is a global-scope function (not a class member function)
     

    z_imagefile_code_to_extension()
    SIGNATURE: string_o z_imagefile_code_to_extension (const int x, int *pi = NULL)
    SYNOPSIS: this returns the string name of a Z Directory image file code. It is a primitive mapping function.
    TRAITS: this is a global-scope function (not a class member function)