Into

Modules

Documentation

classPiiImageFileWriter

#include <PiiImageFileWriter.h>

An operation that writes images into files in standard image formats.

Inherits PiiDefaultOperation

Description

For each input image, a new file will be created. The full name of the new file follows the pattern [outputDirectory]/[namePrefix][nextIndex].[extension]. For example, if outputDirectory = "images", namePrefix = "img", index = 22, and extension = jpg, the output file will be "images/img000022.jpg". The index is incremented by one on each processing round. If an image with the same name already exists, it will be overwritten.

Inputs

imagean image with 8, 24, or 32 bits per pixel. Floating-point images are converted to gray-scale by multiplying by 255 and quantizing into 256 levels.

filenamethe name of the output file. If this input is connected, automatic file name generation will be turned off. The output directory and image prefix are still in effect. For example, if "images/naama.bmp" is read, the output file name will be [outputDirectory]/images/[namePrefix]naama.bmp. If the stripPath flag is true, the file name will be [outputDirectory]/[namePrefix]naama.bmp. If the file name is equipped with an absolute path, the output file will be exactly the same, expect for an optional name prefix.

keythe name of a custom meta-data field to be stored in the image (QString). Note that not all image formats support custom meta-data. The key input must work at a flow level one higher than that of image.

valuethe value corresponding to the key (QString).

metaXX ranges from 0 to the number of metaFields - 1. Receives the value of the meta field X, where X is an index to metaFields. Accepted types are int, double, and QString.

Outputs

filenamethe full name of the current image, including path. The path is relative unless the filename input or the outputDirectory property contains an absolute path.

Properties

bool
autoCreateDirectory

A flag that controls automatic creation of directories.

int
compression

This is an image format specific property that sets the compression of an image.

QString
extension

The file name extension for the files.

bool
lockFiles

Use file locking.

QStringList
metaFields

A list of meta-data fields to be written to the image.

QString
namePrefix

A string the file names will be prefixed with.

int
nextIndex

The index of the next image.

QString
outputDirectory

The directory the writer will store the images in.

QSizeF
pixelSize

The physical size of a pixel.

bool
storeAlpha

Enables/disables storing of image alpha channel with image formats that support alpha.

bool
stripPath

Strip path names from input file names.

bool
writeEnabled

Enable/disable writing.

Constructors and destructor
PiiImageFileWriter
( )

Public member functions

virtual void
check
(
  • bool reset
)

Checks the operation for execution.

template<class T>
bool
writeImage
( )

Write a matrix as an image to a file.

Protected member functions

bool
autoCreateDirectory
( )
int
compression
( )
QString
extension
( )
bool
lockFiles
( )
QStringList
metaFields
( )
QString
namePrefix
( )
int
nextIndex
( )
QString
outputDirectory
( )
QSizeF
pixelSize
( )
virtual void
process
( )

Executes one round of processing.

void
setAutoCreateDirectory
(
  • bool autoCreateDirectory
)
void
setCompression
(
  • int compression
)
void
setExtension
( )
void
setLockFiles
(
  • bool lockFiles
)
void
setMetaFields
( )
void
setNamePrefix
( )
void
setNextIndex
(
  • int index
)
void
setOutputDirectory
( )
void
setPixelSize
(
  • const QSizeF & pixelSize
)
void
setStoreAlpha
(
  • bool storeAlpha
)
void
setStripPath
(
  • bool stripPath
)
void
setWriteEnabled
(
  • bool writeEnabled
)
bool
storeAlpha
( )
bool
stripPath
( )
virtual void
syncEvent
( )

Informs the operation about synchronization events.

bool
writeEnabled
( )

Property details

  • bool autoCreateDirectory

    [read, write]

    A flag that controls automatic creation of directories.

    If the output directory does not exist, the operation will create it for you automatically, if this flag is true. Otherwise the image just won't be written. Default is false.

  • int compression

    [read, write]

    This is an image format specific property that sets the compression of an image.

    For image formats that do not support setting the compression, this value is ignored. The compression must be in the range 0 to 100 or -1. Specify 0 to obtain small compressed files, 100 for large uncompressed files, and -1 (the default) to use the default settings.

  • QString extension

    [read, write]

    The file name extension for the files.

    Despite the name, the extension also determines the format of the file. Valid extensions may vary depending on your setup, but in general at least "png", "jpg", "bmp", and "xpm" are safe. The default extension is bmp. Do not include a dot in the extension. If the filename input is connected, the name read from the input contains an extension, it will override this property.

  • bool lockFiles

    [read, write]

    Use file locking.

    Setting this flag to true causes PiiImageFileWriter to acquire an exclusive (write) lock for the output file before writing to it. This is useful if another process is reading the files concurrently. The default value is false.

    Notes

    • The flock() function is used for locking. Thus, the other process accessing the files must also use flock(). fcntl() won't work.

    • Locking is only available where flock() is available (Unix, not Windows).

    • flock() doesn't work on NFS or Samba shares.

    • flock() locks are process-wide. You cannot use them for mutual exclusion within the same process. That is, you cannot write to the same file with two PiiImageFileWriters in a single configuration.

    To safely read the images written by PiiImageFileWriter, do the following (the C way):

     int handle = open("image.jpg", O_RDONLY);
 // Acquire a shared (read) lock for the file.
 // This call blocks until the file is available.
 flock(handle, LOCK_SH); // returns -1 if locking fails
 char bfr[10];
 // Read data
 read(handle, bfr, 10);
 // Closes the handle and releases the lock
 close(handle);

    The Qt way:

     QFile f("image.jpg");
 f.open(QIODevice::ReadOnly);
 flock(f.handle(), LOCK_SH);
 f.read(...);
 f.close();

  • QStringList metaFields

    [read, write]

    A list of meta-data fields to be written to the image.

    Element X element in this list specifies the name of a meta field corresponding to the value read from the metaX input. If the same key is present in metaFields and the key input, the value read from the metaX input will be used.

  • QString namePrefix

    [read, write]

    A string the file names will be prefixed with.

    The default prefix is "img".

  • int nextIndex

    [read, write]

    The index of the next image.

    Indices are padded with zeros so that their length always equals six. Thus, at most one million images may be written into a single directory without overwriting anything. The default start index is zero.

  • QString outputDirectory

    [read, write]

    The directory the writer will store the images in.

    Relative and absolute paths are OK. An example: "images".

  • QSizeF pixelSize

    [read, write]

    The physical size of a pixel.

    The default value is (1.0, 1.0).

  • bool storeAlpha

    [read, write]

    Enables/disables storing of image alpha channel with image formats that support alpha.

    The default value is false.

  • bool stripPath

    [read, write]

    Strip path names from input file names.

    This flag is useful if you use the name supplied by PiiImageFileReader and want to store images in a different directory. The default value is false.

  • bool writeEnabled

    [read, write]

    Enable/disable writing.

    This property can be used to temporarily disable writing without removing the operation itself. Default is true.

Function details

  • PiiImageFileWriter

    ()

  • virtual void check

    (
    • bool reset
    )
    [virtual]

    Checks the operation for execution.

    This function creates a suitable flow controller by calling createFlowController(). It then sets the flow controller to the active processor and sets the processor as the input controller for all inputs.

    If you change socket groupings in your overridden implementation, please call PiiDefaultOperation::check() after that. Otherwise, your new groupings will not be in effect.

    Reimplemented from PiiDefaultOperation.

  • template<class T>

    bool writeImage

    ()

    Write a matrix as an image to a file.

    Parameters
    matrix
    fileName

    the name of the file. The file name extension determines the type of the file.

    lock

    if true, flock() is used to acquire an exclusive lock on the file before writing. This features is not available on Windows. See above for details.

    Returns

    true if the image was successfully written, false otherwise

  • bool autoCreateDirectory

    ()
    [protected]

  • int compression

    ()
    [protected]

  • QString extension

    ()
    [protected]

  • bool lockFiles

    ()
    [protected]

  • QStringList metaFields

    ()
    [protected]

  • QString namePrefix

    ()
    [protected]

  • int nextIndex

    ()
    [protected]

  • QString outputDirectory

    ()
    [protected]

  • QSizeF pixelSize

    ()
    [protected]

  • virtual void process

    ()
    [protected, virtual]

    Executes one round of processing.

    This function is invoked by the processor if the necessary preconditions for a new processing round are met. This function does all the necessary calculations to create output objects and sends them to output sockets.

    Calls to process(), syncEvent(), and setProperty() are synchronized and cannot occur simultaneously. PiiDefaultOperation ensures this by locking processLock() for reading before calling process().

    Note: With time-consuming operations, one should occasionally check that the operation hasn't been interrupted, i.e. that state() returns Running.

    Exceptions
    PiiExecutionException

    whenever an unrecoverable error occurs during a processing round, the operation is interrupted, or finishes execution due to end of input data.

    Reimplemented from PiiDefaultOperation.

  • void setAutoCreateDirectory

    (
    • bool autoCreateDirectory
    )
    [protected]

  • void setCompression

    (
    • int compression
    )
    [protected]

  • void setExtension

    ()
    [protected]

  • void setLockFiles

    (
    • bool lockFiles
    )
    [protected]

  • void setMetaFields

    ()
    [protected]

  • void setNamePrefix

    ()
    [protected]

  • void setNextIndex

    (
    • int index
    )
    [protected]

  • void setOutputDirectory

    ()
    [protected]

  • void setPixelSize

    (
    • const QSizeF & pixelSize
    )
    [protected]

  • void setStoreAlpha

    (
    • bool storeAlpha
    )
    [protected]

  • void setStripPath

    (
    • bool stripPath
    )
    [protected]

  • void setWriteEnabled

    (
    • bool writeEnabled
    )
    [protected]

  • bool storeAlpha

    ()
    [protected]

  • bool stripPath

    ()
    [protected]

  • virtual void syncEvent

    ()
    [protected, virtual]

    Informs the operation about synchronization events.

    The most typical use of this function is to see when all objects in an input group and all of its child groups have been received. For example, if the operation reads large images from one input and a number of sub-images for each large image from another input, a sync event is sent whenever all the small images that correspond to one large image have been processed. Your implementation may then either just record the synchronized state or to send any buffered data. The default implementation does nothing.

    Calls to process(), syncEvent(), and setProperty() are synchronized and cannot occur simultaneously. PiiDefaultOperation ensures this by locking processLock() for reading before calling syncEvent().

     void MyOperation::syncEvent(SyncEvent* event)
 {
   if (event->type() == SyncEvent::EndInput &&
       event->groupId() == _pLargeImageInput->groupId())
     doWhateverNeededNow();
 }

    Reimplemented from PiiDefaultOperation.

  • bool writeEnabled

    ()
    [protected]
Notes (0)

Add a note

Not a single note added yet. Be the first, add yours.