CameraImageMetadata.h

Go to the documentation of this file.

 
// PROJECT:       Micro-Manager
// SUBSYSTEM:     MMDevice
//-----------------------------------------------------------------------------
// COPYRIGHT:     2026, Board of Regents of the University of Wisconsin System
//
// LICENSE:       This file is distributed under the BSD license.
//                License text is included with the source distribution.
//
//                This file is distributed in the hope that it will be useful,
//                but WITHOUT ANY WARRANTY; without even the implied warranty
//                of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
//
//                IN NO EVENT SHALL THE COPYRIGHT OWNER OR
//                CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
//                INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES.
 
#pragma once
 
#include <algorithm>
#include <cassert>
#include <cstddef>
#include <limits>
#include <sstream>
#include <string>
 
namespace MM {
 
class CameraImageMetadata {
public:
   CameraImageMetadata() { Clear(); }
 
   template <typename V>
   void AddTag(const char* key, V value) {
      assert(key != nullptr);
      std::ostringstream strm;
      strm << value;
      AppendTag(key, strm.str().c_str());
   }
 
   void AddTag(const char* key, const char* value) {
      assert(key != nullptr);
      assert(value != nullptr);
      AppendTag(key, value);
   }
 
   template <typename V>
   void AddTag(const std::string& key, V value) {
      // Once we drop C++14 support, we could replace the char* and std::string&
      // overloads with std::string_view.
      AddTag(key.c_str(), value);
   }
 
   void Clear() {
      buffer_.assign(kCountWidth, ' ');
      buffer_.push_back('\n');
      count_ = 0;
   }
 
   const char* Serialize() const {
      // The serialization format is part of the versioned Device Interface:
      //
      // Header: <tag_count>\n
      // (Spaces are tolerated before and after the tag count; this
      // implementation right-pads the count to a fixed width.)
      // For each tag: s\n<name>\n_\n1\n<value>\n
      // (The 's' indicates "single (not array) tag"; arrays are never used.)
      // (The '_' device-label field is always "_".)
      // (The '1' indicates "read-only"; no actual meaning.)
      //
      // Tags must have unique keys up to DIV 74. In DIV 75+, duplicate keys are
      // permitted on the wire; the last occurrence wins on deserialization.
 
      WriteCountHeader();
      return buffer_.c_str();
   }
 
private:
   // Enough to hold any std::size_t in decimal (20 on 64-bit platforms).
   static constexpr std::size_t kCountWidth =
      std::numeric_limits<std::size_t>::digits10 + 1;
 
   void AppendTag(const char* key, const char* value) {
      buffer_ += "s\n";
      buffer_ += key;
      buffer_ += "\n_\n1\n";
      buffer_ += value;
      buffer_ += '\n';
      ++count_;
   }
 
   void WriteCountHeader() const {
      const std::string s = std::to_string(count_);
      assert(s.size() <= kCountWidth);
      auto out = std::copy(s.begin(), s.end(), buffer_.begin());
      std::fill(out, buffer_.begin() + kCountWidth, ' ');
   }
 
   mutable std::string buffer_;
   std::size_t count_ = 0;
};
 
} // namespace MM