label_semantics.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2025 Povl Filip Sonne-Frederiksen
//
// SPDX-License-Identifier: GPL-3.0-or-later
 
#pragma once
 
#include <cstdint>
#include <stdexcept>
#include <string>
 
#include <opencv2/core.hpp>

 
namespace reusex::core {

inline constexpr uint32_t kUnlabeled = 0;

inline constexpr int kBackgroundApi = -1;

inline constexpr uint16_t kMaxStorableLabel = 65534;

inline constexpr bool is_valid_label(uint32_t label) noexcept {
  return label != kUnlabeled;
}

inline constexpr bool is_out_of_contract_label(uint32_t label) noexcept {
  return label > 0x7FFFFFFFu;
}

inline size_t label_to_index(uint32_t label) {
  if (!is_valid_label(label))
    throw std::out_of_range(
        "label_to_index: label 0 is unlabeled and has no index");
  return static_cast<size_t>(label) - 1;
}
 
// ── Scalar conversions ────────────────────────────────────────────────────

inline uint32_t api_to_point_label(int api_label) {
  if (api_label == kBackgroundApi)
    return kUnlabeled;
  if (api_label < 0)
    throw std::out_of_range("api_to_point_label: negative label " +
                            std::to_string(api_label) +
                            " is not the background sentinel (-1)");
  return static_cast<uint32_t>(api_label);
}

inline int point_label_to_api(uint32_t point_label) {
  if (point_label == kUnlabeled)
    return kBackgroundApi;
  return static_cast<int>(point_label);
}

inline uint16_t api_to_storage(int api_label) {
  if (api_label < kBackgroundApi)
    throw std::out_of_range("api_to_storage: label " +
                            std::to_string(api_label) + " is below -1");
  if (api_label > static_cast<int>(kMaxStorableLabel))
    throw std::out_of_range(
        "api_to_storage: label " + std::to_string(api_label) +
        " exceeds maximum storable label " +
        std::to_string(static_cast<int>(kMaxStorableLabel)) +
        " (would wrap CV_16U storage)");
  return static_cast<uint16_t>(api_label + 1);
}

inline int storage_to_api(uint16_t storage_value) {
  return static_cast<int>(storage_value) - 1;
}
 
// ── Whole-cv::Mat converters ──────────────────────────────────────────────

inline cv::Mat storage_mat_to_api(const cv::Mat &storage) {
  if (storage.empty())
    return cv::Mat();
  if (storage.type() != CV_16UC1)
    throw std::invalid_argument(
        "storage_mat_to_api: expected CV_16UC1 storage image");
  cv::Mat api;
  storage.convertTo(api, CV_32S);
  api -= 1;
  return api;
}

inline cv::Mat api_mat_to_storage(const cv::Mat &api) {
  if (api.empty())
    throw std::invalid_argument("api_mat_to_storage: empty label image");
  if (api.type() != CV_32SC1)
    throw std::invalid_argument(
        "api_mat_to_storage: expected CV_32SC1 API image");
 
  double min_val = 0.0;
  double max_val = 0.0;
  cv::minMaxLoc(api, &min_val, &max_val);
  if (min_val < static_cast<double>(kBackgroundApi))
    throw std::out_of_range("api_mat_to_storage: label " +
                            std::to_string(static_cast<int>(min_val)) +
                            " is below -1");
  if (max_val > static_cast<double>(kMaxStorableLabel))
    throw std::out_of_range(
        "api_mat_to_storage: label " +
        std::to_string(static_cast<int>(max_val)) +
        " exceeds maximum storable label " +
        std::to_string(static_cast<int>(kMaxStorableLabel)) +
        " (would wrap CV_16U storage)");
 
  cv::Mat offset = api + 1;
  cv::Mat storage;
  offset.convertTo(storage, CV_16U);
  return storage;
}
 
} // namespace reusex::core