Loading & saving classes

The classes described in this section are used to load and store DICOM structures (represented by the class imebra::DataSet).

The easiest way to load and store an imebra::DataSet object is by using the static methods of the imebra::CodecFactory class.

BaseStreamInput

class imebra::BaseStreamInput

This class represents a generic input stream.

Specialized classes derived from this one can read data from files stored on the computer’s disks (FileStreamInput) or from memory (MemoryStreamInput).

The client application cannot read the data directly from a BaseStreamInput but must use a StreamReader. Several StreamReader objects can read data from the same BaseStreamInput object.

The StreamReader class is not thread-safe, but different StreamReader objects in different threads can access the same BaseStreamInput object.

Subclassed by imebra::FileStreamInput, imebra::MemoryStreamInput, imebra::Pipe, imebra::TCPStream

Public Functions

virtual imebra::BaseStreamInput~BaseStreamInput()

Destructor.

BaseStreamOutput

class imebra::BaseStreamOutput

This class represents a generic output stream.

Specialized classes derived from this one can write into files on the computer’s disks (FileStreamOutput) or to memory (MemoryStreamOutput).

The application can write into the stream by using a StreamWriter object.

While this class can be used across several threads, a StreamWriter can be used only in one thread.

Several StreamWriter objects (also in different threads) can use the same BaseStreamOutput object.

Subclassed by imebra::FileStreamOutput, imebra::MemoryStreamOutput, imebra::Pipe, imebra::TCPStream

Public Functions

virtual imebra::BaseStreamOutput~BaseStreamOutput()

Destructor.

StreamTimeout

class imebra::StreamTimeout

Triggers a timeout on a selected stream if the class is not deallocated within the specified amount of time.

Public Functions

imebra::StreamTimeoutStreamTimeout(BaseStreamInput &stream, std::uint32_t timeoutSeconds)

Constructor. Starts a separate thread that closes the stream in the parameter if this class destructor is not called before the timeout expires.

Parameters
  • stream: stream that must be closed when the timeout expires
  • timeoutSeconds: timeout in milliseconds

imebra::StreamTimeout~StreamTimeout()

Destructor. If the timeout has not yet expired then terminates the thread that closes the stream, preventing it from closing the stream.

CodecFactory

class imebra::CodecFactory

The CodecFactory class can load or save a DataSet or an Image object using one of the codecs supplied by the Imebra library.

Public Static Functions

static DataSet *imebra::CodecFactoryload(StreamReader &reader, size_t maxSizeBufferLoad = std::numeric_limits<size_t>::max())

Parses the content of the input stream and returns a DataSet representing it.

If none of the codecs supplied by Imebra is able to decode the stream’s content then it throws a CodecWrongFormatError exception.

The read position of the StreamReader is undefined when this method returns.

Return
a DataSet object representing the input stream’s content
Parameters
  • reader: a StreamReader connected to the input stream
  • maxSizeBufferLoad: the maximum size of the tags that are loaded immediately. Tags larger than maxSizeBufferLoad are left on the input stream and loaded only when a ReadingDataHandler or a WritingDataHandler reference them.

static DataSet *imebra::CodecFactoryload(const std::wstring &fileName, size_t maxSizeBufferLoad = std::numeric_limits<size_t>::max())

Parses the content of the input file and returns a DataSet representing it.

If none of the codecs supplied by Imebra is able to decode the file’s content then it throws a CodecWrongFormatError exception.

Return
a DataSet object representing the input file’s content
Parameters
  • fileName: the Unicode name of the input file to read
  • maxSizeBufferLoad: the maximum size of the tags that are loaded immediately. Tags larger than maxSizeBufferLoad are left on the input stream and loaded only when a ReadingDataHandler or a WritingDataHandler reference them.

static DataSet *imebra::CodecFactoryload(const std::string &fileName, size_t maxSizeBufferLoad = std::numeric_limits<size_t>::max())

Parses the content of the input file and returns a DataSet representing it.

If none of the codecs supplied by Imebra is able to decode the file’s content then it throws a CodecWrongFormatError exception.

Return
a DataSet object representing the input file’s content
Parameters
  • fileName: the Utf8 name of the input file to read
  • maxSizeBufferLoad: the maximum size of the tags that are loaded immediately. Tags larger than maxSizeBufferLoad are left on the input stream and loaded only when a ReadingDataHandler or a WritingDataHandler reference them.

static void imebra::CodecFactorysave(const DataSet &dataSet, StreamWriter &writer, codecType_t codecType)

Saves the content of a DataSet object to an output stream using the requested codec.

Parameters
  • dataSet: the DataSet object to save
  • writer: a StreamWriter connected to the output stream
  • codecType: the codec to use to save the DataSet

static void imebra::CodecFactorysave(const DataSet &dataSet, const std::wstring &fileName, codecType_t codecType)

Saves the content of a DataSet object to an output file using the requested codec.

Parameters
  • dataSet: the DataSet object to save
  • fileName: the Unicode name of the output file to create
  • codecType: the codec to use to save the DataSet

static void imebra::CodecFactorysave(const DataSet &dataSet, const std::string &fileName, codecType_t codecType)

Saves the content of a DataSet object to an output file using the requested codec.

Parameters
  • dataSet: the DataSet object to save
  • fileName: the Utf8 name of the output file to create
  • codecType: the codec to use to save the DataSet

static void imebra::CodecFactorysetMaximumImageSize(const std::uint32_t maximumWidth, const std::uint32_t maximumHeight)

Set the maximum image’s width & height accepted by Imebra.

By default both the maximum width and height are set to 4096 pixels.

Parameters
  • maximumWidth: the maximum image’s width accepted by Imebra
  • maximumHeight: the maximum image’s height accepted by Imebra

FileStreamInput

class imebra::FileStreamInput

Represents an input file stream.

Inherits from imebra::BaseStreamInput

Public Functions

imebra::FileStreamInputFileStreamInput(const std::wstring &name)

Constructor.

Parameters
  • name: the path to the file to open in read mode

imebra::FileStreamInputFileStreamInput(const std::string &name)

Constructor.

Parameters
  • name: the path to the file to open in read mode, in encoded in UTF8

imebra::FileStreamInput~FileStreamInput()

Destructor. Closes the file.

FileStreamOutput

class imebra::FileStreamOutput

Represents an output file stream.

Inherits from imebra::BaseStreamOutput

Public Functions

imebra::FileStreamOutputFileStreamOutput(const std::wstring &name)

Constructor.

Parameters
  • name: the path to the file to open in write mode

imebra::FileStreamOutputFileStreamOutput(const std::string &name)

Constructor.

Parameters
  • name: the path to the file to open in write mode

imebra::FileStreamOutput~FileStreamOutput()

Destructor. Closes the file.

MemoryStreamInput

class imebra::MemoryStreamInput

An input stream that reads data from a memory region.

Inherits from imebra::BaseStreamInput

Public Functions

imebra::MemoryStreamInputMemoryStreamInput(const ReadMemory &memory)

Constructor.

Parameters
  • memory: the memory region from which the stream will read the data

imebra::MemoryStreamInputMemoryStreamInput(const ReadWriteMemory &memory)

Constructor.

Parameters
  • memory: the memory region from which the stream will read the data

MemoryStreamOutput

class imebra::MemoryStreamOutput

An output stream that writes data into a memory region.

When new data is written into the memory then it is resized as necessary.

Inherits from imebra::BaseStreamOutput

Public Functions

imebra::MemoryStreamOutputMemoryStreamOutput(const ReadWriteMemory &memory)

Constructor.

Parameters
  • memory: the memory region into which the stream will write the data

StreamReader

class imebra::StreamReader

A StreamReader is used to read data from a BaseStreamInput object.

A StreamReader can be mapped to only a portion of the BaseStreamInput it manages: for instance this is used by the Imebra classes to read Jpeg streams embedded into a DICOM stream.

Warning
The StreamReader object IS NOT THREAD-SAFE: however, several StreamReader objects from different threads can be connected to the same BaseStreamInput object.

Public Functions

imebra::StreamReaderStreamReader(const BaseStreamInput &stream)

Constructor.

Parameters

imebra::StreamReaderStreamReader(const BaseStreamInput &stream, size_t virtualStart, size_t virtualLength)

Constructor.

This version of the constructor limits the portion of the stream that the StreamReader will see.

Parameters
  • stream: the BaseStreamInput object from which the StreamReader will read
  • virtualStart: the first visible byte of the managed stream
  • virtualLength: the number of visible bytes in the managed stream

StreamReader *imebra::StreamReadergetVirtualStream(size_t virtualStreamLength)

Returns a virtual stream that has a restricted view into the stream.

The reading position of this stream advances to the end of the virtual stream.

Return
a virtual stream that sees a limited number of bytes of this stream
Parameters
  • virtualStreamLength: the number of bytes that the virtual stream can read

void imebra::StreamReaderterminate()

Cause the controlled stream to throw StreamClosedError during the mext read operation.

This can be used to cause reading threads to terminate.

StreamWriter

class imebra::StreamWriter

A StreamWriter is used to write data into a BaseStreamOutput object.

A StreamWriter can be mapped to only a portion of the BaseStreamOutput it manages.

Warning
: The StreamWriter object IS NOT THREAD-SAFE: however, several StreamWriter objects from different threads can be connected to the same BaseStreamOutput object.

Public Functions

imebra::StreamWriterStreamWriter(const BaseStreamOutput &stream)

Constructor.

Parameters

imebra::StreamWriterStreamWriter(const BaseStreamOutput &stream, size_t virtualStart, size_t virtualLength)

Constructor.

This version of the constructor limits the portion of the stream that the StreamWriter will be able to use.

Parameters
  • stream: the BaseStreamOutput object on which the StreamWriter will write
  • virtualStart: the first visible byte of the managed stream
  • virtualLength: the number of visible bytes in the managed stream