dicomweb_endpoints.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 <cstdint>
#include <memory>
#include <optional>
#include <span>
#include <string>
#include <string_view>
#include <vector>
 
namespace kcenon::pacs::core {
class dicom_dataset;
} // namespace kcenon::pacs::core
 
namespace kcenon::pacs::storage {
class index_database;
struct study_record;
struct series_record;
struct instance_record;
struct study_query;
struct series_query;
struct instance_query;
} // namespace kcenon::pacs::storage
 
namespace kcenon::pacs::web {
 
struct rest_server_context;
 
namespace dicomweb {
 
struct media_type {
    static constexpr std::string_view dicom = "application/dicom";
    static constexpr std::string_view dicom_json = "application/dicom+json";
    static constexpr std::string_view dicom_xml = "application/dicom+xml";
    static constexpr std::string_view octet_stream = "application/octet-stream";
    static constexpr std::string_view jpeg = "image/jpeg";
    static constexpr std::string_view png = "image/png";
    static constexpr std::string_view jphc = "image/jphc";
    static constexpr std::string_view multipart_related = "multipart/related";
};
 
struct accept_info {
    std::string media_type;
    std::string transfer_syntax;
    float quality = 1.0f;
};
 
[[nodiscard]] auto parse_accept_header(std::string_view accept_header)
    -> std::vector<accept_info>;
 
[[nodiscard]] auto is_acceptable(const std::vector<accept_info>& accept_infos,
                                  std::string_view media_type) -> bool;
 
class multipart_builder {
public:
    explicit multipart_builder(
        std::string_view content_type = media_type::dicom);
 
    void add_part(std::vector<uint8_t> data,
                  std::optional<std::string_view> content_type = std::nullopt);
 
    void add_part_with_location(
        std::vector<uint8_t> data,
        std::string_view location,
        std::optional<std::string_view> content_type = std::nullopt);
 
    [[nodiscard]] auto build() const -> std::string;
 
    [[nodiscard]] auto content_type_header() const -> std::string;
 
    [[nodiscard]] auto boundary() const -> std::string_view;
 
    [[nodiscard]] auto empty() const noexcept -> bool;
 
    [[nodiscard]] auto size() const noexcept -> size_t;
 
private:
    struct part {
        std::vector<uint8_t> data;
        std::string content_type;
        std::string location;
    };
 
    std::string boundary_;
    std::string default_content_type_;
    std::vector<part> parts_;
 
    [[nodiscard]] static auto generate_boundary() -> std::string;
};
 
[[nodiscard]] auto dataset_to_dicom_json(
    const core::dicom_dataset& dataset,
    bool include_bulk_data = false,
    std::string_view bulk_data_uri_prefix = "") -> std::string;
 
[[nodiscard]] auto vr_to_string(uint16_t vr_code) -> std::string;
 
[[nodiscard]] auto is_bulk_data_tag(uint32_t tag) -> bool;
 
// ============================================================================
// STOW-RS Support (Store Over the Web)
// ============================================================================
 
struct multipart_part {
    std::string content_type;       
    std::string content_location;   
    std::string content_id;         
    std::vector<uint8_t> data;      
};
 
class multipart_parser {
public:
    struct parse_error {
        std::string code;       
        std::string message;    
    };
 
    struct parse_result {
        std::vector<multipart_part> parts;  
        std::optional<parse_error> error;   
 
        [[nodiscard]] bool success() const noexcept { return !error.has_value(); }
        [[nodiscard]] explicit operator bool() const noexcept { return success(); }
    };
 
    [[nodiscard]] static auto parse(std::string_view content_type,
                                    std::string_view body) -> parse_result;
 
    [[nodiscard]] static auto extract_boundary(std::string_view content_type)
        -> std::optional<std::string>;
 
    [[nodiscard]] static auto extract_type(std::string_view content_type)
        -> std::optional<std::string>;
 
private:
    [[nodiscard]] static auto parse_part_headers(std::string_view header_section)
        -> std::vector<std::pair<std::string, std::string>>;
};
 
struct store_instance_result {
    bool success = false;                   
    std::string sop_class_uid;              
    std::string sop_instance_uid;           
    std::string retrieve_url;               
    std::optional<std::string> error_code;  
    std::optional<std::string> error_message; 
};
 
struct store_response {
    std::vector<store_instance_result> referenced_instances;  
    std::vector<store_instance_result> failed_instances;      
 
    [[nodiscard]] bool all_success() const noexcept {
        return failed_instances.empty() && !referenced_instances.empty();
    }
 
    [[nodiscard]] bool all_failed() const noexcept {
        return referenced_instances.empty() && !failed_instances.empty();
    }
 
    [[nodiscard]] bool partial_success() const noexcept {
        return !referenced_instances.empty() && !failed_instances.empty();
    }
};
 
struct validation_result {
    bool valid = true;                      
    std::string error_code;                 
    std::string error_message;              
 
    [[nodiscard]] explicit operator bool() const noexcept { return valid; }
 
    static validation_result ok() { return {true, "", ""}; }
    static validation_result error(std::string code, std::string message) {
        return {false, std::move(code), std::move(message)};
    }
};
 
[[nodiscard]] auto validate_instance(
    const core::dicom_dataset& dataset,
    std::optional<std::string_view> target_study_uid = std::nullopt)
    -> validation_result;
 
[[nodiscard]] auto build_store_response_json(
    const store_response& response,
    std::string_view base_url) -> std::string;
 
// ============================================================================
// QIDO-RS Support (Query based on ID for DICOM Objects)
// ============================================================================
 
[[nodiscard]] auto study_record_to_dicom_json(
    const storage::study_record& record,
    std::string_view patient_id,
    std::string_view patient_name) -> std::string;
 
[[nodiscard]] auto series_record_to_dicom_json(
    const storage::series_record& record,
    std::string_view study_uid) -> std::string;
 
[[nodiscard]] auto instance_record_to_dicom_json(
    const storage::instance_record& record,
    std::string_view series_uid,
    std::string_view study_uid) -> std::string;
 
[[nodiscard]] auto parse_study_query_params(
    const std::string& url_params) -> storage::study_query;
 
[[nodiscard]] auto parse_series_query_params(
    const std::string& url_params) -> storage::series_query;
 
[[nodiscard]] auto parse_instance_query_params(
    const std::string& url_params) -> storage::instance_query;
 
// ============================================================================
// Frame Retrieval (WADO-RS)
// ============================================================================
 
[[nodiscard]] auto parse_frame_numbers(std::string_view frame_list)
    -> std::vector<uint32_t>;
 
[[nodiscard]] auto extract_frame(
    std::span<const uint8_t> pixel_data,
    uint32_t frame_number,
    size_t frame_size) -> std::vector<uint8_t>;
 
// ============================================================================
// Rendered Images (WADO-RS)
// ============================================================================
 
enum class rendered_format {
    jpeg,   
    png,    
    jphc    
};
 
struct rendered_params {
    rendered_format format{rendered_format::jpeg};
 
    int quality{75};
 
    std::optional<double> window_center;
 
    std::optional<double> window_width;
 
    uint16_t viewport_width{0};
 
    uint16_t viewport_height{0};
 
    uint32_t frame{1};
 
    std::optional<std::string> presentation_state_uid;
 
    bool burn_annotations{false};
};
 
[[nodiscard]] auto parse_rendered_params(
    std::string_view query_string,
    std::string_view accept_header) -> rendered_params;
 
struct rendered_result {
    std::vector<uint8_t> data;      
    std::string content_type;       
    bool success{false};            
    std::string error_message;      
 
    [[nodiscard]] static rendered_result ok(
        std::vector<uint8_t> d, std::string_view mime_type) {
        return {std::move(d), std::string(mime_type), true, ""};
    }
 
    [[nodiscard]] static rendered_result error(std::string msg) {
        return {{}, "", false, std::move(msg)};
    }
};
 
[[nodiscard]] auto apply_window_level(
    std::span<const uint8_t> pixel_data,
    uint16_t width,
    uint16_t height,
    uint16_t bits_stored,
    bool is_signed,
    double window_center,
    double window_width,
    double rescale_slope = 1.0,
    double rescale_intercept = 0.0) -> std::vector<uint8_t>;
 
[[nodiscard]] auto render_dicom_image(
    std::string_view file_path,
    const rendered_params& params) -> rendered_result;
 
} // namespace dicomweb
 
namespace endpoints {
 
// Internal function - implementation in cpp file
// Registers DICOMweb endpoints with the Crow app
// Called from rest_server.cpp
 
} // namespace endpoints
 
} // namespace kcenon::pacs::web