Working with Image Documents¶

Q2Pix supports the standard operations performed by document-based applications:

Open/close document

Expose document

Edit document

Save/export document

Open/close document¶

The equivalent of opening a document is to create an image document reference with the document’s file. This is done by calling ImgDoc_CreateWithFile.

When done with the document, close it by releasing the document reference with ImgObj_Release.

C_TEXT($imgDocRef)
$imgDocRef:=ImgDoc_CreateWithFile
If ($imgDocRef#"")

      // ...
      // work with the image document
      // ...

   ImgObj_Release ($imgDocRef)
End if

When no file path is passed to ImgDoc_CreateWithFile, the standard file selection dialog is presented to the user.

To open a specific file, pass the pathname:

C_TEXT($imgPath)
$imgPath:="/path/to/image.jpg"

C_TEXT($imgDocRef)
$imgDocRef:=ImgDoc_CreateWithFile ($imgPath)
If ($imgDocRef#"")

      // ...
      // work with the image document
      // ...

   ImgObj_Release ($imgDocRef)
End if

Handling protected PDF documents¶

ImgDoc_CreateWithFile handles protected PDF documents by presenting a password entry dialog to the user.

If the password is known in advance, it can be passed via the options parameter:

C_TEXT($pdfPath;$pdfPass)
$pdfPath:="/path/to/protected.pdf"
$pdfPass:="..."

C_OBJECT($options)
OB SET($options;"Password";$pdfPass)

C_TEXT($imgDocRef)
$imgDocRef:=ImgDoc_CreateWithFile ($imgPath;$options)
If ($imgDocRef#"")

      // ...
      // work with the image document
      // ...

   ImgObj_Release ($imgDocRef)
End if

Expose document¶

The image document reference provides access to the document and frame properties.

Getting image frame geometry¶

The following snippet retrieves the geometric characteristics of the document’s first frame: the point size, and if the document is raster-based the pixel size and resolution.

C_TEXT($imgDocRef)   // The image document reference
C_BOOLEAN($isRaster)   // Retrieved from the document format

   // ...

C_OBJECT($pointSize)
$pointSize:=ImgFrame_GetPointSize ($imgDocRef)

C_REAL($pointWidth;$pointHeight)
$pointWidth:=SizeObj_GetWidth ($pointSize)
$pointHeight:=SizeObj_GetHeight ($pointSize)

If ($isRaster)

   C_OBJECT($pixelSize;$resolution)
   $pixelSize:=RasterFrame_GetPixelSize ($imgDocRef)
   $resolution:=RasterFrame_GetDPISize ($imgDocRef)

   C_LONGINT($pixelWidth;$pixelHeight)
   $pixelWidth:=SizeObj_GetWidth ($pixelSize)
   $pixelHeight:=SizeObj_GetHeight ($pixelSize)

   C_REAL($hRes;$vRes)
   $hRes:=SizeObj_GetWidth ($resolution)
   $vRes:=SizeObj_GetHeight ($resolution)

End if

Getting image frame properties¶

Here is an example of retrieving format-specific image frame properties. For raster frames the color characteristics (color model, bits per channel, alpha info) are retrieved. For PDF pages the media and crop box rectangles are extracted.

C_TEXT($imgDocRef)   // The image document reference
C_BOOLEAN($isRaster;$isPDF)   // Retrieved from the document format

   // ...

C_OBJECT($frameProps)
$frameProps:=ImgFrame_GetProperties ($imgDocRef)

Case of
   : ($isRaster)

      C_TEXT($colorModel)
      C_LONGINT($bitsPerChannel)
      C_BOOLEAN($hasAlpha)

      $colorModel:=OB Get($frameProps;"ColorModel";Is text)
      $bitsPerChannel:=OB Get($frameProps;"BitsPerChannel";Is longint)
      $hasAlpha:=OB Get($frameProps;"HasAlpha";Is Boolean)

   : ($isPDF)

      C_OBJECT($mediaBoxRect;$cropBoxRect)   // 'rect' objects

      $mediaBoxRect:=OB Get($frameProps;"MediaBox";Is object)
      $cropBoxRect:=OB Get($frameProps;"CropBox";Is object)

End case

Creating thumbnails¶

Thumbnails can be created from both raster-based and PDF frames.

The following code creates a thumbnail using default settings: maximum size {160, 160}, format TIFF. The thumbnail can be returned as a BLOB or as a 4D picture.

C_TEXT($imgDocRef)   // The image document reference

   // ...

C_BLOB($thumbData)
$thumbData:=ImgFrame_CreateThumb ($imgDocRef)

C_PICTURE($thumbPict)
$thumbPict:=ImgFrame_CreateThumbPict ($imgDocRef)

Thumbnail creation and encoding settings can be specified via the options parameter:

C_TEXT($imgDocRef)   // The image document reference

   // ...

C_OBJECT($maxPixelSize)
$maxPixelSize:=SizeObj_New(200;200)

C_OBJECT($options)
OB SET($options;"MaxPixelSize";$maxPixelSize)
OB SET($options;"Format";"JPEG")

C_BLOB($thumbData)
$thumbData:=ImgFrame_CreateThumb ($imgDocRef;1;$options)

C_PICTURE($thumbPict)
$thumbPict:=ImgFrame_CreateThumbPict ($imgDocRef;1;$options)

Raster frames may contain embedded thumbnails which can be easily extracted:

C_TEXT($rasterDocRef)   // The raster document reference

   // ...

C_PICTURE($thumbPict)
$thumbPict:=RasterFrame_GetEmbThumbPict ($rasterDocRef)

C_BLOB($thumbData)
$thumbData:=RasterFrame_GetEmbThumb ($rasterDocRef)

Encoding settings can also be specified:

C_TEXT($rasterDocRef)   // The raster document reference

   // ...

C_OBJECT($options)
OB SET($options;"Format";"JPEG")
OB SET($options;"LossyCompressionQuality";0.5)

C_PICTURE($thumbPict)
$thumbPict:=RasterFrame_GetEmbThumbPict ($rasterDocRef;1;$options)

C_BLOB($thumbData)
$thumbData:=RasterFrame_GetEmbThumb ($rasterDocRef;1;$options)

Edit document¶

Image documents can be edited in a number of ways:

By modifying raster frame properties (orientation, resolution, XMP metadata, etc).

By transforming raster frame data (crop, flip, rotate, etc).

By inserting and removing frames.

Edited documents can be reverted to their original state. Raster frame edits can be un-done one at a time, or cancelled all together.

Changing raster frame orientation¶

Frame orientation can be modified to achieve rotation and flipping:

C_TEXT($rasterDocRef)   // The raster document reference

   // ...

   // Rotate orientation by 90 degrees clockwise
RasterFrame_RotOrientationRight ($rasterDocRef)

   // Rotate orientation by 90 degrees counter clockwise
RasterFrame_RotOrientationLeft ($rasterDocRef)

   // Flip orientation horizontally
RasterFrame_FlipOrientationHorz ($rasterDocRef)

   // Flip orientation vertically
RasterFrame_FlipOrientationVert ($rasterDocRef)

The methods above ultimately change the orientation property of the raster frame, which can also be modified directly:

C_TEXT($rasterDocRef)   // The raster document reference

   // ...

C_LONGINT($frameOrientation)
$frameOrientation:=kImgOrientationNormal

RasterFrame_SetOrientation ($rasterDocRef;1;$frameOrientation)

Changing raster frame resolution¶

Raster frame resolution can be modified in a similar way. The following snippet changes the horizontal and vertical resolution of the raster frame to 300 x 300 dpi.

C_TEXT($rasterDocRef)   // The raster document reference

   // ...

C_LONGINT($resolution)
$resolution:=SizeObj_New (300;300)

RasterFrame_SetDPISize ($rasterDocRef;1;$resolution)

Modifying raster frame pixel map¶

The editing of raster frames (including all property modifications discussed above) is implemented at lower level through filters. The following examples demonstrate the use of filters for cropping and flipping raster frame pixel maps.

Crop the raster frame pixel map to the top-left quarter with the “Crop” filter:

C_TEXT($rasterDocRef)   // The raster document reference

   // ...

   // Get the frame pixel size
C_OBJECT($pixelSize)
$pixelSize:=RasterFrame_GetPixelSize ($rasterDocRef)

C_OBJECT($cropRect)
$cropRect:=RectObj_New (0;0;\
   SizeObj_GetWidth ($pixelSize)/2;\
   SizeObj_GetHeight ($pixelSize)/2)

C_OBJECT($filterParams)
OB SET($filterParams;"Rectangle";$cropRect)

RasterFrame_PushFilter ($rasterDocRef;1;"Crop";$filterParams)

Or by calling a higher level convenience method:

C_TEXT($rasterDocRef)   // The raster document reference

   // ...

   // Get the frame pixel size
C_OBJECT($pixelSize)
$pixelSize:=RasterFrame_GetPixelSize ($rasterDocRef)

C_OBJECT($cropRect)
$cropRect:=RectObj_New (0;0;\
   SizeObj_GetWidth ($pixelSize)/2;\
   SizeObj_GetHeight ($pixelSize)/2)

RasterFrame_Crop ($rasterDocRef;1;$cropRect)

Flip the raster frame pixel map horizontally with the “Flip” filter:

C_TEXT($rasterDocRef)  // The raster document reference

  // ...

C_OBJECT($filterParams)
OB SET($filterParams;"Horizontally";True)
OB SET($filterParams;"Vertically";False)

RasterFrame_PushFilter ($rasterDocRef;1;"Flip";$filterParams)

Or by calling a higher level convenience method:

C_TEXT($rasterDocRef)  // The raster document reference

  // ...

RasterFrame_FlipOrientationHorz ($rasterDocRef;1)

Scale the raster frame pixel map to 50% with the “Scale” filter:

C_TEXT($rasterDocRef)  // The raster document reference

  // ...

C_OBJECT($filterParams)
OB SET($filterParams;"ScaleX";0.5)
OB SET($filterParams;"ScaleY";0.5)

RasterFrame_PushFilter ($rasterDocRef;1;"Scale";$filterParams)

Or by calling a higher level convenience method:

C_TEXT($rasterDocRef)  // The raster document reference

  // ...

RasterFrame_Scale ($rasterDocRef;1;0.5)

Adjust raster frame size¶

Let the user adjust the raster frame pixel and/or point size through a convenient dialog:

C_TEXT($rasterDocRef)  // The raster document reference

  // ...

If (RasterFrame_AdjustSize($rasterDocRef;1)=1)

    // The user accepted the dialog and the size modifications were applied

    // ...

End if

Undoing raster frame edits¶

Each raster frame keeps a stack of all filters previously applied to it, and their respective parameters.

Popping the last filter applied to the frame is equivalent to a undo action.

C_TEXT($rasterDocRef)  // The raster document reference

  // ...

  // Modify the frame orientation - equivalent to RasterFrame_SetOrientation
C_OBJECT($filterParams)
OB SET($filterParams;"Orientation";kImgRotated180)

RasterFrame_PushFilter ($rasterDocRef;1;"Orientation";$filterParams)

  // Undo the orientation modification
RasterFrame_PopFilter ($rasterDocRef;1)

Reverting frame and document edits¶

All edits at frame or document level can be reverted:

C_TEXT($imgDocRef)   // The image document reference

   // ...

   // Revert the edits done on the first frame
If (ImgFrame_GetEditsSummary ($imgDocRef;1)#0)
   ImgFrame_RevertEdits ($imgDocRef;1)
End if

   // Revert the edits done on the document (including all frames)
If (ImgDoc_GetEditsSummary ($imgDocRef)#0)
   ImgDoc_RevertEdits ($imgDocRef)
End if

Save/export document¶

Image documents can be saved or exported with a single method call while numerous options allow complete control over the operation. The operation is optimized to avoid re-compression of image data, when possible.

The difference between saving and exporting is semantic – Q2Pix supports both with a single method: ImgDoc_SaveInFile.

Save and Save as...

When using the “Save” menu item in a document-based application, the document is written over the original file and the state of the saved document is reflected in the application. The same happens when using the “Save as...” menu item, only this time the document becomes attached to the new file that has been selected by the user. In both cases the modification status of the document is cleared.

Export

When using the “Export...” menu item in a document-based application, the document is typically saved to a file in another (“foreign”) format. The document does not become attached to the export file, while its modification status remains unchanged.

To save a modified document over its original file in its original format (a common “Save” operation), call ImgDoc_SaveInFile with the filePath parameter set to empty (or to the original file path).

C_TEXT($imgDocRef)   // The image document reference

   // ...

If (ImgDoc_SaveInFile ($imgDocRef)=1)   // Save over the original file
   // Image saved successfully
End if

For a “Save as...” operation, provide the new file path:

C_TEXT($imgDocRef)   // The image document reference
C_TEXT($newFilePath)   // The path of the file to save into

   // ...

If (ImgDoc_SaveInFile ($imgDocRef;$newFilePath)=1)
   // Image saved successfully
End if

After either operation the Q2Pix document is reloaded from the file it was saved in and its modification status is cleared.

When implementing a “Export...” operation, the options have to be set so that the Q2Pix document will not become attached to the exported file. The following snippet shows how to export a Q2Pix document while also changing the target format:

C_TEXT($imgDocRef)   // The image document reference
C_TEXT($exportFilePath)   // The path of the file to export to

   // ...

C_OBJECT($options)
OB SET($options;"Attach";False;"Format";"TIFF")
If (ImgDoc_SaveInFile ($imgDocRef;$exportFilePath;$options)=1)
   // Image exported successfully
End if

After exporting, the Q2Pix document remains attached to the original file and its modification status remains unchanged.

See the documentation for the ImgDoc_SaveInFile method for more information and a list of all supported options.

Saving options dialog¶

To request the image format and associated options before saving:

C_TEXT($imgDocRef)   // The image document reference
C_TEXT($exportFilePath)   // The path of the file to export to

   // ...

C_OBJECT($options)
OB SET($options;"Format";"TIFF")

if (ImgDlog_SavingOptions ($imgDocRef;->$options)=1))
    If (ImgDoc_SaveInFile ($imgDocRef;$exportFilePath;$options)=1)
       // Image saved successfully
    End if
End if

Working with Image Documents¶

Open/close document¶

Handling protected PDF documents¶

Expose document¶

Getting format-related information¶

Getting image frame geometry¶

Getting image frame properties¶

Creating thumbnails¶

Edit document¶

Changing raster frame orientation¶

Changing raster frame resolution¶

Modifying raster frame pixel map¶

Adjust raster frame size¶

Undoing raster frame edits¶

Reverting frame and document edits¶

Save/export document¶

Saving options dialog¶