introduce "frame-of-reference"

CMakeLists.txt

@@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 3.15)
 cmake_policy(SET CMP0091 NEW) # enable new "MSVC runtime library selection" (https://cmake.org/cmake/help/latest/variable/CMAKE_MSVC_RUNTIME_LIBRARY.html)
 
 project(libCZI 
-      VERSION 0.62.7
+      VERSION 0.63.0
       HOMEPAGE_URL "https://github.com/ZEISS/libczi"
       DESCRIPTION "libCZI is an Open Source Cross-Platform C++ library to read and write CZI")
 

Src/CZICmd/execute.cpp

@@ -556,12 +556,12 @@ class CExecuteSingleChannelTileAccessor : CExecuteBase
         sctaOptions.sceneFilter = options.GetSceneIndexSet();
         sctaOptions.useVisibilityCheckOptimization = options.GetUseVisibilityCheckOptimization();
 
-        IntRect roi{ options.GetRectX() ,options.GetRectY(),options.GetRectW(),options.GetRectH() };
+        IntRect roi{ options.GetRectX() ,options.GetRectY(), options.GetRectW(), options.GetRectH() };
         if (options.GetIsRelativeRectCoordinate())
         {
             auto statistics = spReader->GetStatistics();
-            roi.x += statistics.boundingBox.x;
-            roi.y += statistics.boundingBox.y;
+            roi.x += statistics.boundingBoxLayer0Only.x;
+            roi.y += statistics.boundingBoxLayer0Only.y;
         }
 
         auto re = accessor->Get(roi, &coordinate, &sctaOptions);
@@ -676,8 +676,8 @@ class CExecuteChannelComposite : CExecuteBase
         IntRect roi{ options.GetRectX() ,options.GetRectY() ,options.GetRectW(),options.GetRectH() };
         if (options.GetIsRelativeRectCoordinate())
         {
-            roi.x += subBlockStatistics.boundingBox.x;
-            roi.y += subBlockStatistics.boundingBox.y;
+            roi.x += subBlockStatistics.boundingBoxLayer0Only.x;
+            roi.y += subBlockStatistics.boundingBoxLayer0Only.y;
         }
 
         auto accessor = reader->CreateSingleChannelTileAccessor();
@@ -861,8 +861,8 @@ class CExecuteScalingChannelComposite : CExecuteBase
         IntRect roi{ options.GetRectX() ,options.GetRectY() ,options.GetRectW(),options.GetRectH() };
         if (options.GetIsRelativeRectCoordinate())
         {
-            roi.x += subBlockStatistics.boundingBox.x;
-            roi.y += subBlockStatistics.boundingBox.y;
+            roi.x += subBlockStatistics.boundingBoxLayer0Only.x;
+            roi.y += subBlockStatistics.boundingBoxLayer0Only.y;
         }
 
         auto accessor = reader->CreateSingleChannelScalingTileAccessor();

Src/CZICmd/executeBase.cpp

@@ -61,8 +61,8 @@ IntRect CExecuteBase::GetRoiFromOptions(const CCmdLineOptions& options, const Su
     IntRect roi{ options.GetRectX(), options.GetRectY(), options.GetRectW(), options.GetRectH() };
     if (options.GetIsRelativeRectCoordinate())
     {
-        roi.x += subBlockStatistics.boundingBox.x;
-        roi.y += subBlockStatistics.boundingBox.y;
+        roi.x += subBlockStatistics.boundingBoxLayer0Only.x;
+        roi.y += subBlockStatistics.boundingBoxLayer0Only.y;
     }
 
     return roi;

Src/libCZI/CZIReader.cpp

@@ -32,7 +32,7 @@
     return parse_options;
 }
 
-CCZIReader::CCZIReader() : isOperational(false)
+CCZIReader::CCZIReader() : isOperational(false), default_frame_of_reference(CZIFrameOfReference::Invalid)
 {
 }
 
@@ -60,6 +60,17 @@
     }
 
     this->stream = stream;
+    switch (options->default_frame_of_reference)
+    {
+    case CZIFrameOfReference::Invalid:
+    case CZIFrameOfReference::Default:
+        this->default_frame_of_reference = CZIFrameOfReference::RawSubBlockCoordinateSystem;
+        break;
+    default:
+        this->default_frame_of_reference = options->default_frame_of_reference;
+        break;
+    }
+
     this->SetOperationalState(true);
 }
 
@@ -96,6 +107,58 @@
     return this->subBlkDir.GetPyramidStatistics();
 }
 
+/*virtual*/libCZI::IntPointAndFrameOfReference CCZIReader::TransformPoint(const libCZI::IntPointAndFrameOfReference& source_point, libCZI::CZIFrameOfReference destination_frame_of_reference)
+{
+    CZIFrameOfReference source_frame_of_reference_consolidated;
+    switch (source_point.frame_of_reference)
+    {
+    case CZIFrameOfReference::RawSubBlockCoordinateSystem:
+    case CZIFrameOfReference::PixelCoordinateSystem:
+        source_frame_of_reference_consolidated = source_point.frame_of_reference;
+        break;
+    case CZIFrameOfReference::Default:
+        source_frame_of_reference_consolidated = this->default_frame_of_reference;
+        break;
+    default:
+        throw invalid_argument("Unsupported frame-of-reference.");
+    }
+
+    CZIFrameOfReference destination_frame_of_reference_consolidated;
+    switch (destination_frame_of_reference)
+    {
+    case CZIFrameOfReference::RawSubBlockCoordinateSystem:
+    case CZIFrameOfReference::PixelCoordinateSystem:
+        destination_frame_of_reference_consolidated = destination_frame_of_reference;
+        break;
+    case CZIFrameOfReference::Default:
+        destination_frame_of_reference_consolidated = this->default_frame_of_reference;
+        break;
+    default:
+        throw invalid_argument("Unsupported frame-of-reference.");
+    }
+
+    if (destination_frame_of_reference_consolidated == source_frame_of_reference_consolidated)
+    {
+        return { source_frame_of_reference_consolidated, source_point.point };
+    }
+
+    if (source_frame_of_reference_consolidated == CZIFrameOfReference::PixelCoordinateSystem &&
+        destination_frame_of_reference_consolidated == CZIFrameOfReference::RawSubBlockCoordinateSystem)
+    {
+        const auto& statistics = this->subBlkDir.GetStatistics();
+        return libCZI::IntPointAndFrameOfReference{ CZIFrameOfReference::RawSubBlockCoordinateSystem, {source_point.point.x + statistics.boundingBoxLayer0Only.x, source_point.point.y + statistics.boundingBoxLayer0Only.y} };
+    }
+
+    if (source_frame_of_reference_consolidated == CZIFrameOfReference::RawSubBlockCoordinateSystem &&
+        destination_frame_of_reference_consolidated == CZIFrameOfReference::PixelCoordinateSystem)
+    {
+        const auto& statistics = this->subBlkDir.GetStatistics();
+        return libCZI::IntPointAndFrameOfReference{ CZIFrameOfReference::PixelCoordinateSystem, {source_point.point.x - statistics.boundingBoxLayer0Only.x, source_point.point.y - statistics.boundingBoxLayer0Only.y} };
+    }
+
+    throw logic_error("Unsupported frame-of-reference transformation.");
+}
+
 /*virtual*/void CCZIReader::EnumerateSubBlocks(const std::function<bool(int index, const SubBlockInfo& info)>& funcEnum)
 {
     this->ThrowIfNotOperational();
@@ -205,8 +268,8 @@
     this->ThrowIfNotOperational();
     CziReaderCommon::EnumerateSubset(
         std::bind(&CCziAttachmentsDirectory::EnumAttachments, &this->attachmentDir, std::placeholders::_1),
-        contentFileType, 
-        name, 
+        contentFileType,
+        name,
         funcEnum);
 }
 

Src/libCZI/CZIReader.h

@@ -21,6 +21,7 @@ class CCZIReader : public libCZI::ICZIReader, public std::enable_shared_from_thi
     CCziSubBlockDirectory subBlkDir;
     CCziAttachmentsDirectory attachmentDir;
     bool    isOperational;  ///<    If true, then stream, hdrSegmentData and subBlkDir can be considered valid and operational
+    libCZI::CZIFrameOfReference default_frame_of_reference;
 public:
     CCZIReader();
     ~CCZIReader() override = default;
@@ -33,6 +34,7 @@ class CCZIReader : public libCZI::ICZIReader, public std::enable_shared_from_thi
     bool TryGetSubBlockInfo(int index, libCZI::SubBlockInfo* info) const override;
     libCZI::SubBlockStatistics GetStatistics() override;
     libCZI::PyramidStatistics GetPyramidStatistics() override;
+    libCZI::IntPointAndFrameOfReference TransformPoint(const libCZI::IntPointAndFrameOfReference& source_point, libCZI::CZIFrameOfReference destination_frame_of_reference) override;
 
     // interface ISubBlockRepositoryEx
     void EnumerateSubBlocksEx(const std::function<bool(int index, const libCZI::DirectorySubBlockInfo& info)>& funcEnum) override;

Src/libCZI/CziReaderWriter.cpp

@@ -33,7 +33,8 @@
     int key;
     ICziReaderWriter* t;
     ReplaceHelper(int key, ICziReaderWriter* t)
-        :key(key), t(t) {}
+        :key(key), t(t)
+    {}
 
     void operator()(const AddSubBlockInfo& addSbBlkInfo) const
     {
@@ -60,17 +61,17 @@
 void ICziReaderWriter::ReplaceSubBlock(int key, const libCZI::AddSubBlockInfoMemPtr& addSbBlkInfoMemPtr)
 {
     struct ReplaceHelper f(key, this);
-    AddSubBlockHelper::SyncAddSubBlock<ReplaceHelper >(f, addSbBlkInfoMemPtr);
+    AddSubBlockHelper::SyncAddSubBlock<ReplaceHelper>(f, addSbBlkInfoMemPtr);
 }
 void ICziReaderWriter::ReplaceSubBlock(int key, const libCZI::AddSubBlockInfoLinewiseBitmap& addSbInfoLinewise)
 {
     struct ReplaceHelper f(key, this);
-    AddSubBlockHelper::SyncAddSubBlock<ReplaceHelper >(f, addSbInfoLinewise);
+    AddSubBlockHelper::SyncAddSubBlock<ReplaceHelper>(f, addSbInfoLinewise);
 }
 void ICziReaderWriter::ReplaceSubBlock(int key, const libCZI::AddSubBlockInfoStridedBitmap& addSbBlkInfoStrideBitmap)
 {
     struct ReplaceHelper f(key, this);
-    AddSubBlockHelper::SyncAddSubBlock<ReplaceHelper >(f, addSbBlkInfoStrideBitmap);
+    AddSubBlockHelper::SyncAddSubBlock<ReplaceHelper>(f, addSbBlkInfoStrideBitmap);
 }
 
 //--------------------------------------------------------------------------------------------------------
@@ -335,7 +336,7 @@
 
 void CCziReaderWriter::UpdateFileHeader()
 {
-    FileHeaderSegment fhs = { 0 };
+    FileHeaderSegment fhs = {};
 
     fhs.header.AllocatedSize = fhs.header.UsedSize = sizeof(fhs.data);
     memcpy(&fhs.header.Id, &CCZIParse::FILEHDRMAGIC, 16);
@@ -430,7 +431,7 @@
     else
     {
         // if there is no valid CZI-file-header, we now write one
-        FileHeaderSegment fhs = { 0 };
+        FileHeaderSegment fhs = {};
         fhs.header.AllocatedSize = fhs.header.UsedSize = sizeof(fhs.data);
         memcpy(&fhs.header.Id, &CCZIParse::FILEHDRMAGIC, 16);
 
@@ -489,7 +490,7 @@
     this->attachmentDirectory.EnumEntries(
         [&](size_t index, const CCziAttachmentsDirectoryBase::AttachmentEntry& attEntry)->bool
         {
-            if (uint64_t(attEntry.FilePosition) > lastSegmentPos)
+            if (static_cast<uint64_t>(attEntry.FilePosition) > lastSegmentPos)
             {
                 lastSegmentPos = attEntry.FilePosition;
             }
@@ -712,6 +713,58 @@
     return this->sbBlkDirectory.GetPyramidStatistics();
 }
 
+/*virtual*/libCZI::IntPointAndFrameOfReference CCziReaderWriter::TransformPoint(const libCZI::IntPointAndFrameOfReference& source_point, libCZI::CZIFrameOfReference destination_frame_of_reference)
+{
+    CZIFrameOfReference source_frame_of_reference_consolidated;
+    switch (source_point.frame_of_reference)
+    {
+    case CZIFrameOfReference::RawSubBlockCoordinateSystem:
+    case CZIFrameOfReference::PixelCoordinateSystem:
+        source_frame_of_reference_consolidated = source_point.frame_of_reference;
+        break;
+    case CZIFrameOfReference::Default:
+        source_frame_of_reference_consolidated = this->GetDefaultFrameOfReference();
+        break;
+    default:
+        throw invalid_argument("Unsupported frame-of-reference.");
+    }
+
+    CZIFrameOfReference destination_frame_of_reference_consolidated;
+    switch (destination_frame_of_reference)
+    {
+    case CZIFrameOfReference::RawSubBlockCoordinateSystem:
+    case CZIFrameOfReference::PixelCoordinateSystem:
+        destination_frame_of_reference_consolidated = destination_frame_of_reference;
+        break;
+    case CZIFrameOfReference::Default:
+        destination_frame_of_reference_consolidated = this->GetDefaultFrameOfReference();
+        break;
+    default:
+        throw invalid_argument("Unsupported frame-of-reference.");
+    }
+
+    if (destination_frame_of_reference_consolidated == source_frame_of_reference_consolidated)
+    {
+        return { source_frame_of_reference_consolidated, source_point.point };
+    }
+
+    if (source_frame_of_reference_consolidated == CZIFrameOfReference::PixelCoordinateSystem &&
+        destination_frame_of_reference_consolidated == CZIFrameOfReference::RawSubBlockCoordinateSystem)
+    {
+        const auto& statistics = this->GetStatistics();
+        return libCZI::IntPointAndFrameOfReference{ CZIFrameOfReference::RawSubBlockCoordinateSystem, {source_point.point.x + statistics.boundingBoxLayer0Only.x, source_point.point.y + statistics.boundingBoxLayer0Only.y} };
+    }
+
+    if (source_frame_of_reference_consolidated == CZIFrameOfReference::RawSubBlockCoordinateSystem &&
+        destination_frame_of_reference_consolidated == CZIFrameOfReference::PixelCoordinateSystem)
+    {
+        const auto& statistics = this->GetStatistics();
+        return libCZI::IntPointAndFrameOfReference{ CZIFrameOfReference::PixelCoordinateSystem, {source_point.point.x - statistics.boundingBoxLayer0Only.x, source_point.point.y - statistics.boundingBoxLayer0Only.y} };
+    }
+
+    throw logic_error("Unsupported frame-of-reference transformation.");
+}
+
 /*virtual*/void CCziReaderWriter::EnumerateAttachments(const std::function<bool(int index, const libCZI::AttachmentInfo& info)>& funcEnum)
 {
     this->ThrowIfNotOperational();
@@ -874,3 +927,16 @@
         throw logic_error("CCziReaderWriter is already operational.");
     }
 }
+
+libCZI::CZIFrameOfReference CCziReaderWriter::GetDefaultFrameOfReference() const
+{
+    const auto default_frame_of_reference_from_info = this->info->GetDefaultFrameOfReference();
+    switch (default_frame_of_reference_from_info)
+    {
+    case CZIFrameOfReference::RawSubBlockCoordinateSystem:
+    case CZIFrameOfReference::PixelCoordinateSystem:
+        return default_frame_of_reference_from_info;
+    default:
+        return CZIFrameOfReference::RawSubBlockCoordinateSystem;
+    }
+}

Src/libCZI/CziReaderWriter.h

@@ -47,6 +47,7 @@ class CCziReaderWriter : public libCZI::ICziReaderWriter
     bool TryGetSubBlockInfo(int index, libCZI::SubBlockInfo* info) const override;
     libCZI::SubBlockStatistics GetStatistics() override;
     libCZI::PyramidStatistics GetPyramidStatistics() override;
+    libCZI::IntPointAndFrameOfReference TransformPoint(const libCZI::IntPointAndFrameOfReference& source_point, libCZI::CZIFrameOfReference destination_frame_of_reference) override;
 
     // interface IAttachmentRepository
     void EnumerateAttachments(const std::function<bool(int index, const libCZI::AttachmentInfo& info)>& funcEnum) override;
@@ -80,6 +81,7 @@ class CCziReaderWriter : public libCZI::ICziReaderWriter
     void UpdateFileHeader();
     void ThrowIfNotOperational() const;
     void ThrowIfAlreadyInitialized() const;
+    libCZI::CZIFrameOfReference GetDefaultFrameOfReference() const;
 private:
     class CNextSegment
     {

Src/libCZI/Doc/version-history.markdown

@@ -33,4 +33,5 @@ version history                 {#version_history}
  0.62.4             | [117](https://github.com/ZEISS/libczi/pull/117)      | fix build with private RapidJSON library
  0.62.5             | [119](https://github.com/ZEISS/libczi/pull/119)      | fix a discrepancy between code and documentation
  0.62.6             | [120](https://github.com/ZEISS/libczi/pull/120)      | fix workload identity in the azure blob inputstream
- 0.62.7             | [122](https://github.com/ZEISS/libczi/pull/122)      | documentation update
+ 0.62.7             | [122](https://github.com/ZEISS/libczi/pull/122)      | documentation update
+ 0.63.0             | [123](https://github.com/ZEISS/libczi/pull/123)      | introduce "frames-of-reference"

Src/libCZI/SingleChannelPyramidLevelTileAccessor.cpp

@@ -15,7 +15,7 @@
 {
 }
 
-/*virtual*/std::shared_ptr<libCZI::IBitmapData> CSingleChannelPyramidLevelTileAccessor::Get(const libCZI::IntRect& roi, const libCZI::IDimCoordinate* planeCoordinate, const PyramidLayerInfo& pyramidInfo, const ISingleChannelPyramidLayerTileAccessor::Options* pOptions)
+/*virtual*/std::shared_ptr<libCZI::IBitmapData> CSingleChannelPyramidLevelTileAccessor::Get(const libCZI::IntRectAndFrameOfReference& roi, const libCZI::IDimCoordinate* planeCoordinate, const PyramidLayerInfo& pyramidInfo, const ISingleChannelPyramidLayerTileAccessor::Options* pOptions)
 {
     if (pOptions == nullptr)
     {
@@ -34,7 +34,7 @@
     return this->Get(pixelType, roi, planeCoordinate, pyramidInfo, pOptions);
 }
 
-/*virtual*/std::shared_ptr<libCZI::IBitmapData> CSingleChannelPyramidLevelTileAccessor::Get(libCZI::PixelType pixeltype, const libCZI::IntRect& roi, const libCZI::IDimCoordinate* planeCoordinate, const PyramidLayerInfo& pyramidInfo, const libCZI::ISingleChannelPyramidLayerTileAccessor::Options* pOptions)
+/*virtual*/std::shared_ptr<libCZI::IBitmapData> CSingleChannelPyramidLevelTileAccessor::Get(libCZI::PixelType pixeltype, const libCZI::IntRectAndFrameOfReference& roi, const libCZI::IDimCoordinate* planeCoordinate, const PyramidLayerInfo& pyramidInfo, const libCZI::ISingleChannelPyramidLayerTileAccessor::Options* pOptions)
 {
     if (pOptions == nullptr)
     {
@@ -43,31 +43,33 @@
         return this->Get(pixeltype, roi, planeCoordinate, pyramidInfo, &opt);
     }
 
+    const IntRect roi_raw_sub_block_cs = this->sbBlkRepository->TransformRectangle(roi, CZIFrameOfReference::RawSubBlockCoordinateSystem).rectangle;
     const int sizeOfPixel = CalcSizeOfPixelOnLayer0(pyramidInfo);
-    const IntSize sizeOfBitmap{ static_cast<std::uint32_t>(roi.w / sizeOfPixel),static_cast<std::uint32_t>(roi.h / sizeOfPixel) };
+    const IntSize sizeOfBitmap{ static_cast<std::uint32_t>(roi_raw_sub_block_cs.w / sizeOfPixel),static_cast<std::uint32_t>(roi_raw_sub_block_cs.h / sizeOfPixel) };
     if (sizeOfBitmap.w == 0 || sizeOfBitmap.h == 0)
     {
         // TODO
         throw runtime_error("error");
     }
 
     auto bmDest = GetSite()->CreateBitmap(pixeltype, sizeOfBitmap.w, sizeOfBitmap.h);
-    this->InternalGet(bmDest.get(), roi.x, roi.y, sizeOfPixel, planeCoordinate, pyramidInfo, *pOptions);
+    this->InternalGet(bmDest.get(), roi_raw_sub_block_cs.x, roi_raw_sub_block_cs.y, sizeOfPixel, planeCoordinate, pyramidInfo, *pOptions);
     return bmDest;
 }
 
-/*virtual*/void CSingleChannelPyramidLevelTileAccessor::Get(libCZI::IBitmapData* pDest, int xPos, int yPos, const libCZI::IDimCoordinate* planeCoordinate, const PyramidLayerInfo& pyramidInfo, const Options* pOptions)
+/*virtual*/void CSingleChannelPyramidLevelTileAccessor::Get(libCZI::IBitmapData* pDest, const libCZI::IntPointAndFrameOfReference& position, const libCZI::IDimCoordinate* planeCoordinate, const PyramidLayerInfo& pyramidInfo, const Options* pOptions)
 {
     if (pOptions == nullptr)
     {
         Options opt;
         opt.Clear();
-        this->Get(pDest, xPos, yPos, planeCoordinate, pyramidInfo, &opt);
+        this->Get(pDest, position, planeCoordinate, pyramidInfo, &opt);
         return;
     }
 
+    const IntPoint point_raw_sub_block_cs = this->sbBlkRepository->TransformPoint(position, CZIFrameOfReference::RawSubBlockCoordinateSystem).point;
     const int sizeOfPixel = CalcSizeOfPixelOnLayer0(pyramidInfo);
-    this->InternalGet(pDest, xPos, yPos, sizeOfPixel, planeCoordinate, pyramidInfo, *pOptions);
+    this->InternalGet(pDest, point_raw_sub_block_cs.x, point_raw_sub_block_cs.y, sizeOfPixel, planeCoordinate, pyramidInfo, *pOptions);
 }
 
 void CSingleChannelPyramidLevelTileAccessor::InternalGet(libCZI::IBitmapData* pDest, int xPos, int yPos, int sizeOfPixelOnLayer0, const libCZI::IDimCoordinate* planeCoordinate, const PyramidLayerInfo& pyramidInfo, const Options& options)