Class ICZIReader

Class ICZIReader#

Nested Relationships#

Nested Types#

Inheritance Relationships#

Base Types#

Class Documentation#

class ICZIReader : public libCZI::ISubBlockRepository, public libCZI::ISubBlockRepositoryEx, public libCZI::IAttachmentRepository#

This interface is used to represent the CZI-file. A note on thread-safety - all methods of this interface may be called from multiple threads concurrently.

Public Functions

virtual void Open(const std::shared_ptr<IStream> &stream, const OpenOptions *options = nullptr) = 0#

Opens the specified stream and reads the global information from the CZI-document. The stream passed in will have its refcount incremented, a reference is held until Close is called (or the instance is destroyed).

Remark

If this method is called twice (assuming successful return), then an exception of type std::logic_error is thrown.

Parameters:

  • stream – The stream object.

  • options – (Optional) Options for controlling the operation. If nullptr is given here, then the default settings are used.

virtual FileHeaderInfo GetFileHeaderInfo() = 0#

Gets the file header information.

Returns:

The file header information.

virtual std::shared_ptr<IMetadataSegment> ReadMetadataSegment() = 0#

Reads the metadata segment from the stream.

Remark

If the class is not operational (i.e. Open was not called or Open was not successful), then an exception of type std::logic_error is thrown.

Returns:

The metadata segment.

virtual std::shared_ptr<IAccessor> CreateAccessor(AccessorType accessorType) = 0#

Creates an accessor for the sub-blocks. See also the various typed methods: CreateSingleChannelTileAccessor, CreateSingleChannelPyramidLayerTileAccessor and CreateSingleChannelScalingTileAccessor.

Remark

If the class is not operational (i.e. Open was not called or Open was not successful), then an exception of type std::logic_error is thrown.

Parameters:

accessorType – The type of the accessor.

Returns:

The accessor (of the requested type).

virtual void Close() = 0#

Closes CZI-reader. The underlying stream-object will be released, and further calls to other methods will fail. The stream is also closed when the object is destroyed, so it is usually not necessary to explicitly call Close. Note that the stream is not closed immediately (or - there is no guarantee that on return from this call all references to the stream object are released). Concurrently executing operations continue to use the stream and keep it referenced until they are finished.

inline std::shared_ptr<ISingleChannelTileAccessor> CreateSingleChannelTileAccessor()#

Creates a single channel tile accessor.

Returns:

The new single channel tile accessor.

inline std::shared_ptr<ISingleChannelPyramidLayerTileAccessor> CreateSingleChannelPyramidLayerTileAccessor()#

Creates a single channel pyramid-layer accessor.

Returns:

The new single channel tile accessor.

inline std::shared_ptr<ISingleChannelScalingTileAccessor> CreateSingleChannelScalingTileAccessor()#

Creates a single channel scaling tile accessor.

Returns:

The new single channel scaling tile accessor.

struct OpenOptions#

This structure gathers the settings for controlling the ‘Open’ operation of the CZIReader-class.

Public Types

enum class SubBlockDirectoryInfoPolicy : std::uint8_t#

This enum is used to specify the policy which defines which information is considered authoritative (in the description of a sub-block) - either the information in the sub-block directory or in the sub-block header. Also, it controls how to handle a discrepancy here - either throw an exception if a discrepancy is encountered or ignore a discrepancy (and go with the respective information for decoding a bitmap as is). Note that the values defined here are used to define a bit-field. The first bit (bit 0) is used to distinguish between sub-block-directory precedence and sub-block-header precedence. The value ‘PrecedenceMask’ is used to mask this bit. Bit 7 is used to indicate whether a discrepancy is to be ignored or whether an error is to be reported. Historically, libCZI (up to version 0.63.2) used to give precedence fo the sub-block header information, and it did not report a discrepancy.

Values:

enumerator SubBlockDirectoryPrecedence#

The sub-block-directory information is used for the sub-blocks.

enumerator SubBlockHeaderPrecedence#

The sub-block information is used for the sub-blocks.

enumerator PrecedenceMask#

Bit-mask allowing to extract the relevant bits for “precedence”.

enumerator IgnoreDiscrepancy#

Flag allowing to choose whether a discrepancy is to be ignored (true) or whether an exception is to be thrown (false) when accessing the sub-block.

Public Functions

inline void SetDefault()#

Sets the default.

Public Members

bool lax_subblock_coordinate_checks = {true}#

This option controls whether the lax parameter validation when parsing the dimension-entry of a subblock is to be used. Previous versions of libCZI did not check whether certain values in the file have the expected value. If those values are different than expected, this meant that libCZI would not be able to deal with the document properly. If lax checking of this is disabled, then Open will fail with a corresponding exception. The default is to enable lax checking (for compatibility with previous libCZI-versions), but users are encouraged to disable this for new code.

bool ignore_sizem_for_pyramid_subblocks = {false}#

This option controls whether the size-M-attribute of a pyramid-subblocks is to be ignored (when parsing and validating the dimension-entry of a subblock). This flag is only relevant if strict validation is enabled (i.e. lax_subblock_coordinate_checks is ‘false’). If lax_subblock_coordinate_checks is true, then this flag has no effect. This is useful as some versions of software creating CZI-files used to write bogus values for size-M, and those files would otherwise not be usable with strict validation enabled. If this bogus size-M is ignored, then the files can be used without problems.

libCZI::CZIFrameOfReference default_frame_of_reference = {libCZI::CZIFrameOfReference::Invalid}#

The default frame-of-reference which is to be used by the reader-object. This determines which frame-of-reference is used when the enum value “CZIFrameOfReference::Default” is used with an operation of the reader-object. If the value specified here is “CZIFrameOfReference::Invalid” or “CZIFrameOfReference::Default”, then “CZIFrameOfReference::RawSubBlockCoordinateSystem” will be used.

SubBlockDirectoryInfoPolicy subBlockDirectoryInfoPolicy = {SubBlockDirectoryInfoPolicy::SubBlockDirectoryPrecedence}#

This bitfield is used to specify the policy which information is considered authoritative in the construction of a sub-block - either the information in the sub-block directory or in the sub-block header. Also, it controls how to handle a discrepancy in this respect - either throw an exception if a discrepancy is encountered or ignore it.

Contents