## QPix v3 | ## At a glance

1. Installing QuickTime and registering QPix
2. Importing image files
3. Getting information on image files and pictures
4. Displaying images on 4D forms
5. Creating thumbnails
6. Transforming images
7. Compressing images
8. Acquiring images from external devices
9. Document management
10. Working with image tags (TIFF, Exif, GPS, IPTC, QT)

Installing QuickTime and registering QPix

QPix requires a full installation of the latest version of QuickTime. While still editing the On Startup database method, check the currently installed QuickTime version with QPx_GetQuickTimeVersion. Note that QuickTime 6 or late ris required.

To use QPix without the 30-minute evaluation limit, purchase a Developer license for your development platform, and install the license key in your database following the installation instructions.

Importing image files

Before working with a disk file that contains an image, make sure this file can be handled by QPix. To do this use QPx_TestImageFile.

To import an image file into your database, you have the following options:

- Read the image into a 4D picture using QPx_ReadImageFileInPicture. Once the image is transferred into a 4D picture, you can work with it using QPix's powerful set of picture handling commands.
- Display the image in a QPix plug-in area on a 4D form using QPx_SetAreaImageFile. Read more on the possibilities of QPix areas in Displaying images on 4D forms.

Getting information on image files and pictures

Image file information

After you've made sure you're dealing with an image file that can be handled with QPix, you can use the commands supplied by QPix to retrieve various pieces of information about the image file:

- To get properties, such as dimensions, color depth and resolution, use QPx_GetImageFileInfo.
- To retrieve the color space, use QPx_GetImageFileColorSpace.
- To retrieve the name of the color profile, if any, use QPx_GetImageFileColorProfile.

Picture information

QPix offers commands for getting picture information. These commands accept a picture variable as main parameter:

- To get properties, such as dimensions, color depth and resolution, use QPx_GetPictureInfo.
- To retrieve information on picture compression (QT), use QPx_GetCompressedPictureInfo.

Displaying images on 4D forms

Using a QPix plug-in area is the recommended way for displaying images on 4D forms. Obviously you could also use a 4D picture variable object, but the possibilities would be inferior, let alone that earlier versions of 4D (incl. 6.5) cannot display QT-compressed pictures on Windows.

QPix areas are fully portable across platforms and they offer extraordinary image handling facilities, such as scrollable display, zoom, navigation in multi-page images, and more.

Setting up a QPix area

QPix area setup can't get any easier: it's codeless. Simply create a QPix plug-in area in the form editor and invoke the Advanced Properties Dialog. Set your options on this intuitive dialog and you're ready to go. When the form opens, QPix will be set up down to the slightest detail.

Area settings can be set also with code, using QPix's command set:

- To configure the visual appearance of a QPix area, use QPx_SetAreaStyle
- To configure the visual parts of a scrollable QPix area, use QPx_SetAreaParts
- To configure the user tools in a scrollable QPix area, use QPx_SetAreaTools and QPx_SetAreaCurrentTool
- To configure various options of a QPix area, use QPx_SetAreaFlags
- To configure image alignment within the QPix area, use QPx_SetAreaScrollOffset
- To apply zooms and fits, use QPx_SetAreaZoomFactor

Assigning an image to the QPix area

- To assign an image file to the area, use QPx_SetAreaImage File
- To assign a picture variable to the area, use QPx_SetAreaPicture
- To assign a picture field to the area, either get the field in a variable or use 4D's convention for automatic binding: the picture field must have the same name as the plug-in area plus an extra underscore ("_") at the end.

More information on multi-page images can be found in Document Management.

Creating thumbnails

Every professional image database is expected to deliver great-looking thumbnails. QPix takes advantage of the latest developments in QuickTime 6 to deliver the best thumbnails ever produced and displayed in 4D databases.

With QPix you can get a thumnail in the following ways:

- Get (no control) the embedded thumbnail from eligible image files with QPx_GetImageFileEmbeddedThumb
- Create (full control) a thumbnail from an image file with QPx_CreateImageFileThumbnail
- Create (full control) a thumbnail from a 4D picture variable with QPx_CreatePictureThumbnail

Assuming QT 6 or later is present, QPix will create high-quality thumbnails using QT's bicubic interpolation. However, if speed is more important than quality, you can instruct QPix to deliver standard quality thumbnails.

For ultimate results, add sharpness using the commands discussed in Transforming images.

Transforming images

QPix includes commands for cropping, rotating, flipping and filtering. All these commands can be applied to area images, as well as to picture variables (offscreen).

Cropping: crop the image to any rectangle using QPx_CropAreaImage or QPx_CropPicture

Rotation: enter a rotation angle and rotate the image using QPx_RotateAreaImage or QPx_RotatePicture.

Flipping: flip the image in any possible sense using QPx_FlipAreaImage or QPx_FlipPicture.

Filtering: QuickTime's includes filter components that can apply many commonly used filters to still images. QPix has commands that let you take full advantage of QT filters in the following two ways:

- by invoking QT's standard filter dialog with QPx_DoFilterSettingsDialog, and by subsequently applying such settings using QPx_FilterAreaImage or QPx_FilterPicture.
- using the direct filter commands for brightness/contrast, sharpness, blurring, RGB balance and HSL balance. Direct filter commands exist for area images and pictures:
  - QPx_BrithnessContrastAreaImg and QPx_BrightnessContrastPicture
  - QPx_SharpenAreaImage and QPx_SharpenPicture
  - QPx_BlurAreaImage and QPx_BlurPicture
  - QPx_RGBBalanceAreaImage and QPx_RGBBalancePicture
  - QPx_HSLBalanceAreaImage and QPx_HSLBalancePicture

Lossless transformations on JPEG files

With QPix, JPEG files can be transformed losslessly, i.e. without having to decompress/recompress. Available geometric transformations are:

- rotation by increments of 90 degrees
- flipping horizontally and vertically
- mirroring across the diagonal axes

All geometric transformations can be applied with QPx_TranscodeJPEGFile and QPx_TranscodeJPEGBLOB. More information on other JPEG transcoding possibilities in the JPEG transcoding section of the Reference Manual.

Compressing images

The need for compression is inherent in image databases because even small pictures are huge compared to other kinds of data: a typical small thumbnail occupies 20K, roughly the same as 10 pages of plain text or a 4D set for 165000 records!

QPix provides easy access to QuickTime compression services. To let users configure one of the available compression methods, bring up QuickTime's compression settings dialog using QPx_DoCodecSettingsDialog.

- Having chosen compression settings, use QPx_CompressPicture to compress a 4D picture.
- To retrieve information on picture compression, use QPx_GetCompressedPictureInfo.

Compression is also available as an option of the exporting process: it is possible to bring up the compression setings dialog also through the export settings dialog (invoked with QPx_DoExportSettingsDialog). This procedure is common in configuring the compression options before using QPx_ExportPicture, QPx_ExportImageFile and QPx_ExportAreaImage.

Acquiring images from external devices

QPix 3 offers enhanced capabilities for acquiring still images from a variety of external devices, such as digicams (digital still cameras), scanners, camcorders (digital video cameras), webcams (low-cost digital video cameras), etc.

In QPix v3 all acquisition standards have been organized into 3 "protocols":

- TWAIN: covers TWAIN devices on all supported platforms.
- Picture Transfer Protocol (PTP): covers Image Capture and Windows Image Acquisition.
- Video: supports QuickTime and DirectShow video.

TWAIN: TWAIN is a specification that is commonly used for interfacing applications with scanners and other imaging devices. Available on all platforms: MacOS 8/9 and X, Windows 98, 2000, ME and XP.

Picture Transfer Protocol (PTP): a standard defined by the Photographic and Imaging Manufacturers Association (PIMA), PTP is the method for interfacing applications with digital cameras. PTP is implemented on MacOS X (Image Capture) and Windows Me/XP (Windows Image Acquisition-WIA).

Video: uses QuickTime video grabbing on MacOS (all versions) and DirectShow on Windows (all versions) to acquire still images into applications from video cameras (camcorders, webcams, etc).

QPix's approach unifies the way in which 4D applications communicate with all these devices and standards, thus providing developers with an elegant command set and minimal learning curve. In most cases you will be able to do the job with this simple 1-2-3 procedure:

1. Start with QPx_AcqSelectDevice to select the device you will be acquiring from.
2. Set the destination folder for the acquired image files with QPx_AcqSetImageFolder
3. Acquire to disk using QPx_AcqGetSingleImage or QPx_AcqGetMultipleImages, or into memory using QPx_AcqGetPicture

For more sophisticated acquisitions, custom interfaces, and detailed control using your own callback method, use QPx_AcqRunSession and the rest of the commands discussed in the Acquisition section of the Reference Manual.

Document management

QPix 3's document management features complement its advanced scanning features which include for the first time support for scanners with Automatic Document Feeder and Duplex options.

Multi-page TIFF and PDF document construction

Multi-page TIFF and PDF document construction is part of a typical document management workflow: entire documents consisting of many pages containing mostly text, are scanned using high-throughput scanners. The paper document is thus transformed into an electronic multi-page file which can easily be stored, retrieved, visualized and printed on demand.

Multi-page TIFF files can be created using QPx_CreateMultipageTIFFFile. This command supports the popular CCITT Fax G3/G4 compressions that produce very small files, making them ideal for electronic storage and distribution.

Multi-page PDF documents can be created uting the QPx_CreatePDFFile plug-in command.

On-screen multi-page navigation

With QPix you can very easily construct a viewer for your multi-page TIFF and PDF files: just configure the QPix area to include the page navigation widget and you are ready to go!

With a bit of code you can also create custom viewers with your own look-and-feel, custom buttons, etc.

PDF viewing

QPix 3 provides support for viewing multi-page PDF files. PDF viewing is based on MacOS X's native PDF support, and on the AFPL Ghostscript Postscript interpreter on Windows, therefore you can have your own PDF viewer inside your 4D applications without licensing any Adobe product.

Working with image tags (TIFF, Exif, GPS, IPTC, QT)

Image tags is a QPix term for what is also called "metadata" (=data about the data). Tags hold information about various aspects of the image, such as caption, copyright holder, acquisition date, location, and so on.

QPix reads IPTC, TIFF, EXIF and QuickTime tags. The relevant commands are discussed in the Tags section of the Reference Manual.