dicom_element.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2021-2025, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include "dicom_tag.h"
#include "result.h"
 
#include <kcenon/pacs/encoding/vr_type.h>
 
#include <cstdint>
#include <cstring>
#include <span>
#include <stdexcept>
#include <string>
#include <string_view>
#include <type_traits>
#include <vector>
 
namespace kcenon::pacs::core {
 
// Forward declaration to break circular dependency
class dicom_dataset;
 
class dicom_element {
public:
    dicom_element(dicom_tag tag, encoding::vr_type vr) noexcept;
 
    dicom_element(dicom_tag tag, encoding::vr_type vr,
                  std::span<const uint8_t> data);
 
    dicom_element(const dicom_element&);
 
    dicom_element(dicom_element&&) noexcept;
 
    auto operator=(const dicom_element&) -> dicom_element&;
 
    auto operator=(dicom_element&&) noexcept -> dicom_element&;
 
    ~dicom_element();
 
    // ========================================================================
    // Factory Methods
    // ========================================================================
 
    [[nodiscard]] static auto from_string(dicom_tag tag, encoding::vr_type vr,
                                          std::string_view value) -> dicom_element;
 
    template <typename T>
        requires std::is_arithmetic_v<T>
    [[nodiscard]] static auto from_numeric(dicom_tag tag, encoding::vr_type vr,
                                           T value) -> dicom_element;
 
    template <typename T>
        requires std::is_arithmetic_v<T>
    [[nodiscard]] static auto from_numeric_list(dicom_tag tag, encoding::vr_type vr,
                                                std::span<const T> values) -> dicom_element;
 
    // ========================================================================
    // Accessors
    // ========================================================================
 
    [[nodiscard]] constexpr auto tag() const noexcept -> dicom_tag { return tag_; }
 
    [[nodiscard]] constexpr auto vr() const noexcept -> encoding::vr_type { return vr_; }
 
    [[nodiscard]] auto length() const noexcept -> uint32_t {
        return static_cast<uint32_t>(data_.size());
    }
 
    [[nodiscard]] auto raw_data() const noexcept -> std::span<const uint8_t> {
        return data_;
    }
 
    [[nodiscard]] auto is_empty() const noexcept -> bool { return data_.empty(); }
 
    // ========================================================================
    // String Value Access
    // ========================================================================
 
    [[nodiscard]] auto as_string() const -> kcenon::pacs::Result<std::string>;
 
    [[nodiscard]] auto as_string_list() const
        -> kcenon::pacs::Result<std::vector<std::string>>;
 
    // ========================================================================
    // Numeric Value Access
    // ========================================================================
 
    template <typename T>
        requires std::is_arithmetic_v<T>
    [[nodiscard]] auto as_numeric() const -> kcenon::pacs::Result<T>;
 
    template <typename T>
        requires std::is_arithmetic_v<T>
    [[nodiscard]] auto as_numeric_list() const -> kcenon::pacs::Result<std::vector<T>>;
 
    // ========================================================================
    // Sequence Access
    // ========================================================================
 
    [[nodiscard]] auto is_sequence() const noexcept -> bool {
        return vr_ == encoding::vr_type::SQ;
    }
 
    [[nodiscard]] auto sequence_item_count() const noexcept -> std::size_t;
 
    [[nodiscard]] auto sequence_item(std::size_t index) const
        -> const dicom_dataset&;
 
    [[nodiscard]] auto sequence_item(std::size_t index) -> dicom_dataset&;
 
    [[nodiscard]] auto sequence_items() -> std::vector<dicom_dataset>&;
 
    [[nodiscard]] auto sequence_items() const -> const std::vector<dicom_dataset>&;
 
    void add_sequence_item(dicom_dataset item);
 
    // ========================================================================
    // Modification
    // ========================================================================
 
    void set_value(std::span<const uint8_t> data);
 
    void set_string(std::string_view value);
 
    template <typename T>
        requires std::is_arithmetic_v<T>
    void set_numeric(T value);
 
private:
    dicom_tag tag_;
    encoding::vr_type vr_;
    std::vector<uint8_t> data_;
    std::vector<dicom_dataset> sequence_items_;  // Used only when VR == SQ
 
    [[nodiscard]] auto apply_padding(std::string_view str) const -> std::string;
 
    [[nodiscard]] static auto remove_padding(std::string_view str,
                                             encoding::vr_type vr) -> std::string;
};
 
// ============================================================================
// Template Implementations
// ============================================================================
 
template <typename T>
    requires std::is_arithmetic_v<T>
auto dicom_element::from_numeric(dicom_tag tag, encoding::vr_type vr,
                                 T value) -> dicom_element {
    dicom_element elem{tag, vr};
    elem.set_numeric(value);
    return elem;
}
 
template <typename T>
    requires std::is_arithmetic_v<T>
auto dicom_element::from_numeric_list(dicom_tag tag, encoding::vr_type vr,
                                      std::span<const T> values) -> dicom_element {
    dicom_element elem{tag, vr};
    std::vector<uint8_t> data(values.size() * sizeof(T));
 
    for (size_t i = 0; i < values.size(); ++i) {
        std::memcpy(data.data() + i * sizeof(T), &values[i], sizeof(T));
    }
 
    elem.set_value(data);
    return elem;
}
 
template <typename T>
    requires std::is_arithmetic_v<T>
auto dicom_element::as_numeric() const -> kcenon::pacs::Result<T> {
    if (data_.size() < sizeof(T)) {
        return kcenon::pacs::pacs_error<T>(
            kcenon::pacs::error_codes::data_size_mismatch,
            "Insufficient data for numeric conversion: expected " +
                std::to_string(sizeof(T)) + " bytes, got " +
                std::to_string(data_.size()));
    }
 
    T result{};
    std::memcpy(&result, data_.data(), sizeof(T));
    return kcenon::pacs::ok(result);
}
 
template <typename T>
    requires std::is_arithmetic_v<T>
auto dicom_element::as_numeric_list() const -> kcenon::pacs::Result<std::vector<T>> {
    if (data_.size() % sizeof(T) != 0) {
        return kcenon::pacs::pacs_error<std::vector<T>>(
            kcenon::pacs::error_codes::data_size_mismatch,
            "Data size not aligned for numeric type: " +
                std::to_string(data_.size()) + " bytes is not divisible by " +
                std::to_string(sizeof(T)));
    }
 
    const size_t count = data_.size() / sizeof(T);
    std::vector<T> result(count);
 
    for (size_t i = 0; i < count; ++i) {
        std::memcpy(&result[i], data_.data() + i * sizeof(T), sizeof(T));
    }
 
    return kcenon::pacs::ok(result);
}
 
template <typename T>
    requires std::is_arithmetic_v<T>
void dicom_element::set_numeric(T value) {
    data_.resize(sizeof(T));
    std::memcpy(data_.data(), &value, sizeof(T));
}
 
}  // namespace kcenon::pacs::core