Encoder/decoder for Explicit VR Little Endian transfer syntax. More...

#include <explicit_vr_codec.h>

Collaboration diagram for kcenon::pacs::encoding::explicit_vr_codec:

Public Types
template<typename T >
using	result = kcenon::pacs::Result<T>
	Result type for decode operations using kcenon::pacs::Result<T> pattern.

Static Public Member Functions
static std::vector< uint8_t >	encode (const core::dicom_dataset &dataset)
	Encode a dataset to bytes using Explicit VR Little Endian.

static result< core::dicom_dataset >	decode (std::span< const uint8_t > data)
	Decode bytes to a dataset using Explicit VR Little Endian.

static std::vector< uint8_t >	encode_element (const core::dicom_element &element)
	Encode a single element to bytes.

static result< core::dicom_element >	decode_element (std::span< const uint8_t > &data)
	Decode a single element from bytes.

Static Private Member Functions
static void	encode_sequence (std::vector< uint8_t > &buffer, const core::dicom_element &element)

static void	encode_sequence_item (std::vector< uint8_t > &buffer, const core::dicom_dataset &item)

static result< core::dicom_element >	decode_undefined_length (core::dicom_tag tag, vr_type vr, std::span< const uint8_t > &data)

static result< core::dicom_dataset >	decode_sequence_item (std::span< const uint8_t > &data)

Detailed Description

Encoder/decoder for Explicit VR Little Endian transfer syntax.

Explicit VR encoding has two formats depending on VR:

Standard VRs (16-bit length): ┌─────────────────────────────────────────────────────┐ │ Data Element │ ├───────────┬───────────┬────────┬──────────┬─────────┤ │ Group │ Element │ VR │ Length │ Value │ │ (2 bytes) │ (2 bytes) │(2 char)│ (2 bytes)│ │ │ LE │ LE │ ASCII │ LE │ │ └───────────┴───────────┴────────┴──────────┴─────────┘ VRs: AE, AS, AT, CS, DA, DS, DT, FL, FD, IS, LO, LT, PN, SH, SL, SS, ST, TM, UI, UL, US

Extended VRs (32-bit length): ┌──────────────────────────────────────────────────────────────┐ │ Data Element │ ├───────────┬───────────┬────────┬──────────┬──────────┬───────┤ │ Group │ Element │ VR │ Reserved │ Length │ Value │ │ (2 bytes) │ (2 bytes) │(2 char)│ (2 bytes)│ (4 bytes)│ │ │ LE │ LE │ ASCII │ 0x0000 │ LE │ │ └───────────┴───────────┴────────┴──────────┴──────────┴───────┘ VRs: OB, OD, OF, OL, OV, OW, SQ, SV, UC, UN, UR, UT, UV

See also: DICOM PS3.5 Section 7.1.2

Definition at line 61 of file explicit_vr_codec.h.

Member Typedef Documentation

◆ result

template<typename T >

using kcenon::pacs::encoding::explicit_vr_codec::result = kcenon::pacs::Result<T>

Result type for decode operations using kcenon::pacs::Result<T> pattern.

Definition at line 67 of file explicit_vr_codec.h.

Member Function Documentation

◆ decode()

explicit_vr_codec::result< core::dicom_dataset > kcenon::pacs::encoding::explicit_vr_codec::decode ( std::span< const uint8_t > data )

staticnodiscard

Decode bytes to a dataset using Explicit VR Little Endian.

Parameters

data	The bytes to decode

Returns: Result containing the decoded dataset or an error

Definition at line 188 of file explicit_vr_codec.cpp.

                                 {
    core::dicom_dataset dataset;
 
    while (!data.empty()) {
        // Peek at tag to check for sequence delimiters
        if (data.size() >= 4) {
            uint16_t group = read_le16(data.data());
            uint16_t elem = read_le16(data.data() + 2);
            core::dicom_tag tag{group, elem};
 
            // Stop at sequence delimiter
            if (is_sequence_delimiter(tag)) {
                break;
            }
            // Stop at item delimiter
            if (is_item_delimiter(tag)) {
                break;
            }
        }
 
        auto result = decode_element(data);
        if (!result.is_ok()) {
            return kcenon::pacs::pacs_error<core::dicom_dataset>(
                result.error().code,
                result.error().message);
        }
 
        dataset.insert(std::move(result.value()));
    }
 
    return dataset;
}

References decode_element(), kcenon::pacs::core::dicom_dataset::insert(), and kcenon::pacs::pacs_error().

Referenced by kcenon::pacs::network::dimse::dimse_message::decode(), and decode_sequence_item().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ decode_element()

explicit_vr_codec::result< core::dicom_element > kcenon::pacs::encoding::explicit_vr_codec::decode_element ( std::span< const uint8_t > & data )

staticnodiscard

Decode a single element from bytes.

The span reference is advanced past the decoded element.

Parameters

data	Reference to the data span (will be modified)

Returns: Result containing the decoded element or an error

Definition at line 222 of file explicit_vr_codec.cpp.

                                  {
    // Need at least 8 bytes for standard format: tag (4) + VR (2) + length (2)
    if (data.size() < 8) {
        return make_codec_error<core::dicom_element>(
            kcenon::pacs::error_codes::insufficient_data,
            "Insufficient data to decode element");
    }
 
    // Read tag
    uint16_t group = read_le16(data.data());
    uint16_t elem = read_le16(data.data() + 2);
    core::dicom_tag tag{group, elem};
 
    // Special handling for sequence delimiter/item tags (implicit VR format)
    if (is_special_tag(tag)) {
        data = data.subspan(8);
 
        // For delimiter tags, return a placeholder element
        return core::dicom_element(tag, vr_type::UN);
    }
 
    // Read VR (2 ASCII characters)
    char vr_chars[2];
    vr_chars[0] = static_cast<char>(data[4]);
    vr_chars[1] = static_cast<char>(data[5]);
    std::string_view vr_str(vr_chars, 2);
 
    auto vr_opt = from_string(vr_str);
    if (!vr_opt) {
        return make_codec_error<core::dicom_element>(
            kcenon::pacs::error_codes::unknown_vr,
            "Unknown VR type");
    }
    vr_type vr = *vr_opt;
 
    uint32_t length;
    size_t header_size;
 
    // Determine length format based on VR
    if (has_explicit_32bit_length(vr)) {
        // Extended format: need 12 bytes total
        if (data.size() < 12) {
            return make_codec_error<core::dicom_element>(
                kcenon::pacs::error_codes::insufficient_data,
                "Insufficient data for extended VR format");
        }
        // Skip reserved 2 bytes, then read 4-byte length
        length = read_le32(data.data() + 8);
        header_size = 12;
    } else {
        // Standard format: 2-byte length
        length = read_le16(data.data() + 6);
        header_size = 8;
    }
 
    data = data.subspan(header_size);
 
    // Handle undefined length (sequences and encapsulated data)
    if (length == UNDEFINED_LENGTH) {
        return decode_undefined_length(tag, vr, data);
    }
 
    // Check if we have enough data
    if (data.size() < length) {
        return make_codec_error<core::dicom_element>(
            kcenon::pacs::error_codes::insufficient_data,
            "Insufficient data for element value");
    }
 
    // Read value
    auto value_data = data.subspan(0, length);
    data = data.subspan(length);
 
    return core::dicom_element(tag, vr, value_data);
}

References decode_undefined_length(), kcenon::pacs::encoding::from_string(), kcenon::pacs::encoding::has_explicit_32bit_length(), kcenon::pacs::error_codes::insufficient_data, kcenon::pacs::encoding::UN, kcenon::pacs::error_codes::unknown_vr, and vr.

Referenced by decode(), and decode_sequence_item().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ decode_sequence_item()

explicit_vr_codec::result< core::dicom_dataset > kcenon::pacs::encoding::explicit_vr_codec::decode_sequence_item ( std::span< const uint8_t > & data )

staticprivate

Definition at line 387 of file explicit_vr_codec.cpp.

                                  {
    // Read Item tag and length (implicit VR format for item tags)
    if (data.size() < 8) {
        return make_codec_error<core::dicom_dataset>(
            kcenon::pacs::error_codes::insufficient_data,
            "Insufficient data for sequence item");
    }
 
    uint16_t group = read_le16(data.data());
    uint16_t elem = read_le16(data.data() + 2);
    core::dicom_tag tag{group, elem};
 
    if (!is_item_tag(tag)) {
        return make_codec_error<core::dicom_dataset>(
            kcenon::pacs::error_codes::invalid_sequence,
            "Expected Item tag for sequence item");
    }
 
    uint32_t item_length = read_le32(data.data() + 4);
    data = data.subspan(8);
 
    if (item_length == UNDEFINED_LENGTH) {
        // Decode until Item Delimitation Item
        core::dicom_dataset item;
 
        while (!data.empty()) {
            if (data.size() < 4) {
                return make_codec_error<core::dicom_dataset>(
                    kcenon::pacs::error_codes::insufficient_data,
                    "Insufficient data for item delimiter check");
            }
 
            uint16_t elem_group = read_le16(data.data());
            uint16_t elem_elem = read_le16(data.data() + 2);
            core::dicom_tag elem_tag{elem_group, elem_elem};
 
            if (is_item_delimiter(elem_tag)) {
                // Skip delimiter
                data = data.subspan(8);
                break;
            }
 
            auto elem_result = decode_element(data);
            if (!elem_result.is_ok()) {
                return make_codec_error<core::dicom_dataset>(
                    elem_result.error().code,
                    elem_result.error().message);
            }
 
            item.insert(std::move(elem_result.value()));
        }
 
        return item;
    }
 
    // Explicit item length
    if (data.size() < item_length) {
        return make_codec_error<core::dicom_dataset>(
            kcenon::pacs::error_codes::insufficient_data,
            "Insufficient data for item content");
    }
 
    auto item_data = data.subspan(0, item_length);
    data = data.subspan(item_length);
 
    return decode(item_data);
}

References decode(), decode_element(), kcenon::pacs::error_codes::insufficient_data, and kcenon::pacs::error_codes::invalid_sequence.

Referenced by decode_undefined_length().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ decode_undefined_length()

explicit_vr_codec::result< core::dicom_element > kcenon::pacs::encoding::explicit_vr_codec::decode_undefined_length	(	core::dicom_tag	tag,
		vr_type	vr,
		std::span< const uint8_t > &	data )

staticprivate

Definition at line 299 of file explicit_vr_codec.cpp.

                                  {
    // If this is a sequence (SQ), decode sequence items
    if (vr == vr_type::SQ) {
        core::dicom_element seq_element(tag, vr_type::SQ);
 
        while (!data.empty()) {
            // Check for sequence delimitation
            if (data.size() < 8) {
                return make_codec_error<core::dicom_element>(
                    kcenon::pacs::error_codes::insufficient_data,
                    "Insufficient data for sequence delimiter");
            }
 
            uint16_t item_group = read_le16(data.data());
            uint16_t item_elem = read_le16(data.data() + 2);
            core::dicom_tag item_tag{item_group, item_elem};
 
            // Check for sequence delimitation item
            if (is_sequence_delimiter(item_tag)) {
                // Skip the delimiter (8 bytes: tag + length)
                data = data.subspan(8);
                break;
            }
 
            // Must be an Item tag
            if (!is_item_tag(item_tag)) {
                return make_codec_error<core::dicom_element>(
                    kcenon::pacs::error_codes::invalid_sequence,
                    "Expected Item tag in sequence");
            }
 
            // Decode the sequence item
            auto item_result = decode_sequence_item(data);
            if (!item_result.is_ok()) {
                return make_codec_error<core::dicom_element>(
                    item_result.error().code,
                    item_result.error().message);
            }
 
            seq_element.sequence_items().push_back(std::move(item_result.value()));
        }
 
        return seq_element;
    }
 
    // For other undefined-length elements (like encapsulated pixel data),
    // read until we find a sequence delimitation item
    std::vector<uint8_t> accumulated_data;
 
    while (!data.empty()) {
        if (data.size() < 8) {
            return make_codec_error<core::dicom_element>(
                kcenon::pacs::error_codes::insufficient_data,
                "Insufficient data for encapsulated data");
        }
 
        uint16_t item_group = read_le16(data.data());
        uint16_t item_elem = read_le16(data.data() + 2);
        core::dicom_tag item_tag{item_group, item_elem};
 
        // Check for sequence delimitation item
        if (is_sequence_delimiter(item_tag)) {
            data = data.subspan(8);
            break;
        }
 
        // For encapsulated data, read item tag + length + data
        if (is_item_tag(item_tag)) {
            uint32_t item_length = read_le32(data.data() + 4);
            data = data.subspan(8);
 
            if (item_length != UNDEFINED_LENGTH && data.size() >= item_length) {
                accumulated_data.insert(accumulated_data.end(),
                                        data.begin(), data.begin() + item_length);
                data = data.subspan(item_length);
            }
        } else {
            return make_codec_error<core::dicom_element>(
                kcenon::pacs::error_codes::invalid_sequence,
                "Invalid tag in encapsulated data");
        }
    }
 
    return core::dicom_element(tag, vr, accumulated_data);
}

References decode_sequence_item(), kcenon::pacs::error_codes::insufficient_data, kcenon::pacs::error_codes::invalid_sequence, kcenon::pacs::core::dicom_element::sequence_items(), kcenon::pacs::encoding::SQ, and vr.

Referenced by decode_element().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ encode()

std::vector< uint8_t > kcenon::pacs::encoding::explicit_vr_codec::encode ( const core::dicom_dataset & dataset )

staticnodiscard

Encode a dataset to bytes using Explicit VR Little Endian.

Parameters

dataset The dataset to encode

Returns: Encoded byte vector

Definition at line 95 of file explicit_vr_codec.cpp.

                                      {
    std::vector<uint8_t> buffer;
    buffer.reserve(4096);  // Initial capacity
 
    for (const auto& [tag, element] : dataset) {
        auto encoded = encode_element(element);
        buffer.insert(buffer.end(), encoded.begin(), encoded.end());
    }
 
    return buffer;
}

References encode_element().

Referenced by kcenon::pacs::network::dimse::dimse_message::encode(), and encode_sequence_item().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ encode_element()

std::vector< uint8_t > kcenon::pacs::encoding::explicit_vr_codec::encode_element ( const core::dicom_element & element )

staticnodiscard

Encode a single element to bytes.

Parameters

element The element to encode

Returns: Encoded byte vector

Definition at line 108 of file explicit_vr_codec.cpp.

                                      {
    std::vector<uint8_t> buffer;
 
    // Write tag (4 bytes: group + element, little-endian)
    write_le16(buffer, element.tag().group());
    write_le16(buffer, element.tag().element());
 
    // Write VR (2 ASCII characters)
    auto vr_str = to_string(element.vr());
    buffer.push_back(static_cast<uint8_t>(vr_str[0]));
    buffer.push_back(static_cast<uint8_t>(vr_str[1]));
 
    // Handle sequences specially
    if (element.is_sequence()) {
        encode_sequence(buffer, element);
        return buffer;
    }
 
    // Get padded data
    auto data = element.raw_data();
    auto padded_data = pad_to_even(element.vr(), data);
    uint32_t length = static_cast<uint32_t>(padded_data.size());
 
    // Write length based on VR type
    if (has_explicit_32bit_length(element.vr())) {
        // Extended format: 2 reserved bytes + 4 byte length
        write_le16(buffer, 0x0000);  // Reserved
        write_le32(buffer, length);
    } else {
        // Standard format: 2 byte length
        write_le16(buffer, static_cast<uint16_t>(length));
    }
 
    // Write value
    buffer.insert(buffer.end(), padded_data.begin(), padded_data.end());
 
    return buffer;
}

References encode_sequence(), kcenon::pacs::encoding::has_explicit_32bit_length(), kcenon::pacs::core::dicom_element::is_sequence(), kcenon::pacs::encoding::pad_to_even(), kcenon::pacs::core::dicom_element::raw_data(), kcenon::pacs::core::dicom_element::tag(), kcenon::pacs::encoding::to_string(), and kcenon::pacs::core::dicom_element::vr().

Referenced by encode().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ encode_sequence()

void kcenon::pacs::encoding::explicit_vr_codec::encode_sequence	(	std::vector< uint8_t > &	buffer,
		const core::dicom_element &	element )

staticprivate

Definition at line 148 of file explicit_vr_codec.cpp.

                                                                           {
    // Write reserved bytes for SQ VR (uses 32-bit length)
    write_le16(buffer, 0x0000);
 
    // Write undefined length for sequence
    write_le32(buffer, UNDEFINED_LENGTH);
 
    // Encode each sequence item
    const auto& items = element.sequence_items();
    for (const auto& item : items) {
        encode_sequence_item(buffer, item);
    }
 
    // Write sequence delimitation item (implicit VR encoding for delimiters)
    write_le16(buffer, ITEM_GROUP);
    write_le16(buffer, SEQ_DELIM_ELEMENT);
    write_le32(buffer, 0);  // Length is always 0 for delimiter
}

References encode_sequence_item(), and kcenon::pacs::core::dicom_element::sequence_items().

Referenced by encode_element().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ encode_sequence_item()

void kcenon::pacs::encoding::explicit_vr_codec::encode_sequence_item	(	std::vector< uint8_t > &	buffer,
		const core::dicom_dataset &	item )

staticprivate

Definition at line 168 of file explicit_vr_codec.cpp.

                                                                             {
    // Write Item tag (implicit VR encoding for item tags)
    write_le16(buffer, ITEM_GROUP);
    write_le16(buffer, ITEM_TAG_ELEMENT);
 
    // Encode item content first to determine length
    auto item_content = encode(item);
 
    // Write item length
    write_le32(buffer, static_cast<uint32_t>(item_content.size()));
 
    // Write item content
    buffer.insert(buffer.end(), item_content.begin(), item_content.end());
}

References encode().

Referenced by encode_sequence().

Here is the call graph for this function:

Here is the caller graph for this function:

The documentation for this class was generated from the following files:

include/kcenon/pacs/encoding/explicit_vr_codec.h
src/encoding/explicit_vr_codec.cpp

Public Types

Static Public Member Functions

Static Private Member Functions

Detailed Description

Member Typedef Documentation

◆ result

Member Function Documentation

◆ decode()

◆ decode_element()

◆ decode_sequence_item()

◆ decode_undefined_length()

◆ encode()

◆ encode_element()

◆ encode_sequence()

◆ encode_sequence_item()