dicom_dataset.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_element.h"
#include "dicom_tag.h"
 
#include <kcenon/pacs/encoding/vr_type.h>
 
#include <initializer_list>
#include <map>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <type_traits>
 
namespace kcenon::pacs::core {
 
class dicom_dataset {
public:
    using storage_type = std::map<dicom_tag, dicom_element>;
 
    using iterator = storage_type::iterator;
 
    using const_iterator = storage_type::const_iterator;
 
    // ========================================================================
    // Construction
    // ========================================================================
 
    dicom_dataset() = default;
 
    dicom_dataset(const dicom_dataset&) = default;
 
    dicom_dataset(dicom_dataset&&) noexcept = default;
 
    auto operator=(const dicom_dataset&) -> dicom_dataset& = default;
 
    auto operator=(dicom_dataset&&) noexcept -> dicom_dataset& = default;
 
    ~dicom_dataset() = default;
 
    // ========================================================================
    // Element Access
    // ========================================================================
 
    [[nodiscard]] auto contains(dicom_tag tag) const noexcept -> bool;
 
    [[nodiscard]] auto get(dicom_tag tag) noexcept -> dicom_element*;
 
    [[nodiscard]] auto get(dicom_tag tag) const noexcept -> const dicom_element*;
 
    // ========================================================================
    // Convenience Accessors
    // ========================================================================
 
    [[nodiscard]] auto get_string(dicom_tag tag,
                                  std::string_view default_value = "") const
        -> std::string;
 
    template <typename T>
        requires std::is_arithmetic_v<T>
    [[nodiscard]] auto get_numeric(dicom_tag tag) const -> std::optional<T>;
 
    // ========================================================================
    // Sequence Access
    // ========================================================================
 
    [[nodiscard]] auto has_sequence(dicom_tag tag) const noexcept -> bool;
 
    [[nodiscard]] auto get_sequence(dicom_tag tag) const noexcept
        -> const std::vector<dicom_dataset>*;
 
    [[nodiscard]] auto get_sequence(dicom_tag tag) noexcept
        -> std::vector<dicom_dataset>*;
 
    [[nodiscard]] auto get_or_create_sequence(dicom_tag tag)
        -> std::vector<dicom_dataset>&;
 
    // ========================================================================
    // Private Tag Access
    // ========================================================================
 
    [[nodiscard]] auto get_private_creator(dicom_tag private_data_tag) const
        -> std::optional<std::string>;
 
    [[nodiscard]] auto get_private_block(std::string_view creator_id,
                                          uint16_t group) const
        -> std::vector<const dicom_element*>;
 
    auto set_private_element(std::string_view creator_id, uint16_t group,
                             uint8_t element_offset, encoding::vr_type vr,
                             std::string_view value) -> std::optional<dicom_tag>;
 
    auto remove_private_block(std::string_view creator_id, uint16_t group)
        -> size_t;
 
    auto cleanup_orphaned_creators() -> size_t;
 
    [[nodiscard]] auto validate_private_tags() const -> std::vector<dicom_tag>;
 
    // ========================================================================
    // Modification
    // ========================================================================
 
    void insert(dicom_element element);
 
    void set_string(dicom_tag tag, encoding::vr_type vr, std::string_view value);
 
    template <typename T>
        requires std::is_arithmetic_v<T>
    void set_numeric(dicom_tag tag, encoding::vr_type vr, T value);
 
    auto remove(dicom_tag tag) -> bool;
 
    void clear() noexcept;
 
    // ========================================================================
    // Iteration
    // ========================================================================
 
    [[nodiscard]] auto begin() noexcept -> iterator;
 
    [[nodiscard]] auto end() noexcept -> iterator;
 
    [[nodiscard]] auto begin() const noexcept -> const_iterator;
 
    [[nodiscard]] auto end() const noexcept -> const_iterator;
 
    [[nodiscard]] auto cbegin() const noexcept -> const_iterator;
 
    [[nodiscard]] auto cend() const noexcept -> const_iterator;
 
    // ========================================================================
    // Size Operations
    // ========================================================================
 
    [[nodiscard]] auto size() const noexcept -> size_t;
 
    [[nodiscard]] auto empty() const noexcept -> bool;
 
    // ========================================================================
    // Utility Operations
    // ========================================================================
 
    [[nodiscard]] auto copy_with_tags(std::initializer_list<dicom_tag> tags) const
        -> dicom_dataset;
 
    [[nodiscard]] auto copy_with_tags(std::span<const dicom_tag> tags) const
        -> dicom_dataset;
 
    void merge(const dicom_dataset& other);
 
    void merge(dicom_dataset&& other);
 
private:
    storage_type elements_;
};
 
// ============================================================================
// Template Implementations
// ============================================================================
 
template <typename T>
    requires std::is_arithmetic_v<T>
auto dicom_dataset::get_numeric(dicom_tag tag) const -> std::optional<T> {
    const auto* elem = get(tag);
    if (elem == nullptr) {
        return std::nullopt;
    }
 
    auto result = elem->as_numeric<T>();
    if (result.is_ok()) {
        return result.value();
    }
    return std::nullopt;
}
 
template <typename T>
    requires std::is_arithmetic_v<T>
void dicom_dataset::set_numeric(dicom_tag tag, encoding::vr_type vr, T value) {
    insert(dicom_element::from_numeric<T>(tag, vr, value));
}
 
}  // namespace kcenon::pacs::core