kcenon::pacs::encoding::explicit_vr_big_endian_codec Class Reference

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

#include <explicit_vr_big_endian_codec.h>

Collaboration diagram for kcenon::pacs::encoding::explicit_vr_big_endian_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 Big Endian.
static result< core::dicom_dataset >	decode (std::span< const uint8_t > data)
	Decode bytes to a dataset using Explicit VR Big 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 std::vector< uint8_t >	to_big_endian (vr_type vr, std::span< const uint8_t > data)
	Convert element value from little-endian to big-endian.
static std::vector< uint8_t >	from_big_endian (vr_type vr, std::span< const uint8_t > data)
	Convert element value from big-endian to little-endian.

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 Big Endian transfer syntax.

Explicit VR Big Endian encoding has the same structure as Little Endian but with big-endian byte ordering for all multi-byte numeric values:

Standard VRs (16-bit length): ┌─────────────────────────────────────────────────────┐ │ Data Element │ ├───────────┬───────────┬────────┬──────────┬─────────┤ │ Group │ Element │ VR │ Length │ Value │ │ (2 bytes) │ (2 bytes) │(2 char)│ (2 bytes)│ │ │ BE │ BE │ ASCII │ BE │ BE │ └───────────┴───────────┴────────┴──────────┴─────────┘

Extended VRs (32-bit length): ┌──────────────────────────────────────────────────────────────┐ │ Data Element │ ├───────────┬───────────┬────────┬──────────┬──────────┬───────┤ │ Group │ Element │ VR │ Reserved │ Length │ Value │ │ (2 bytes) │ (2 bytes) │(2 char)│ (2 bytes)│ (4 bytes)│ │ │ BE │ BE │ ASCII │ 0x0000 │ BE │ BE │ └───────────┴───────────┴────────┴──────────┴──────────┴───────┘

Byte swapping is required for:

• Tag group and element numbers
• Length fields (16-bit and 32-bit)
• Numeric VR values (US, UL, SS, SL, FL, FD, AT)
• Bulk data VRs (OW, OL, OF, OD)

Note

This transfer syntax is retired in DICOM 2024 but implementation is required for legacy system interoperability.

See also

DICOM PS3.5 Section 7.1.2

Definition at line 69 of file explicit_vr_big_endian_codec.h.

Member Typedef Documentation

result

template<typename T >

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

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

Definition at line 75 of file explicit_vr_big_endian_codec.h.

Member Function Documentation

decode()

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

staticnodiscard

Decode bytes to a dataset using Explicit VR Big Endian.

Parameters

data	The bytes to decode

Returns

Result containing the decoded dataset or an error

Definition at line 257 of file explicit_vr_big_endian_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_be16(data.data());
            uint16_t elem = read_be16(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(), kcenon::pacs::pacs_error(), and kcenon::pacs::encoding::read_be16().

Referenced by decode_sequence_item().

Here is the call graph for this function:

Here is the caller graph for this function:

decode_element()

explicit_vr_big_endian_codec::result< core::dicom_element > kcenon::pacs::encoding::explicit_vr_big_endian_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 291 of file explicit_vr_big_endian_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 (big-endian)
    uint16_t group = read_be16(data.data());
    uint16_t elem = read_be16(data.data() + 2);
    core::dicom_tag tag{group, elem};
 
    // Special handling for sequence delimiter/item tags
    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 (big-endian)
        length = read_be32(data.data() + 8);
        header_size = 12;
    } else {
        // Standard format: 2-byte length (big-endian)
        length = read_be16(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 and convert from big-endian
    auto value_data = data.subspan(0, length);
    data = data.subspan(length);
 
    // Convert from big-endian to native (little-endian)
    auto le_data = from_big_endian(vr, value_data);
 
    return core::dicom_element(tag, vr, le_data);
}

References decode_undefined_length(), from_big_endian(), kcenon::pacs::encoding::from_string(), kcenon::pacs::encoding::has_explicit_32bit_length(), kcenon::pacs::error_codes::insufficient_data, kcenon::pacs::encoding::read_be16(), kcenon::pacs::encoding::read_be32(), 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_big_endian_codec::result< core::dicom_dataset > kcenon::pacs::encoding::explicit_vr_big_endian_codec::decode_sequence_item ( std::span< const uint8_t > & data )

staticprivate

Definition at line 463 of file explicit_vr_big_endian_codec.cpp.

                                  {
    // Read Item tag and length (big-endian)
    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_be16(data.data());
    uint16_t elem = read_be16(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_be32(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_be16(data.data());
            uint16_t elem_elem = read_be16(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, kcenon::pacs::error_codes::invalid_sequence, kcenon::pacs::encoding::read_be16(), and kcenon::pacs::encoding::read_be32().

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_big_endian_codec::result< core::dicom_element > kcenon::pacs::encoding::explicit_vr_big_endian_codec::decode_undefined_length ( core::dicom_tag tag, vr_type vr, std::span< const uint8_t > & data )

staticprivate

Definition at line 371 of file explicit_vr_big_endian_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_be16(data.data());
            uint16_t item_elem = read_be16(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_be16(data.data());
        uint16_t item_elem = read_be16(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_be32(data.data() + 4);
            data = data.subspan(8);
 
            if (item_length != UNDEFINED_LENGTH && data.size() >= item_length) {
                // Convert from big-endian
                auto item_data = data.subspan(0, item_length);
                auto le_item = from_big_endian(vr, item_data);
                accumulated_data.insert(accumulated_data.end(),
                                        le_item.begin(), le_item.end());
                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(), from_big_endian(), kcenon::pacs::error_codes::insufficient_data, kcenon::pacs::error_codes::invalid_sequence, kcenon::pacs::encoding::read_be16(), kcenon::pacs::encoding::read_be32(), 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_big_endian_codec::encode ( const core::dicom_dataset & dataset )

staticnodiscard

Encode a dataset to bytes using Explicit VR Big Endian.

Parameters

dataset

The dataset to encode

Returns

Encoded byte vector

Definition at line 160 of file explicit_vr_big_endian_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 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_big_endian_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 173 of file explicit_vr_big_endian_codec.cpp.

                                      {
    std::vector<uint8_t> buffer;
 
    // Write tag (4 bytes: group + element, big-endian)
    write_be16(buffer, element.tag().group());
    write_be16(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 and convert to big-endian
    auto data = element.raw_data();
    auto padded_data = pad_to_even(element.vr(), data);
    auto be_data = to_big_endian(element.vr(), padded_data);
    uint32_t length = static_cast<uint32_t>(be_data.size());
 
    // Write length based on VR type
    if (has_explicit_32bit_length(element.vr())) {
        // Extended format: 2 reserved bytes + 4 byte length
        write_be16(buffer, 0x0000);  // Reserved
        write_be32(buffer, length);
    } else {
        // Standard format: 2 byte length
        write_be16(buffer, static_cast<uint16_t>(length));
    }
 
    // Write value (already byte-swapped)
    buffer.insert(buffer.end(), be_data.begin(), be_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(), to_big_endian(), kcenon::pacs::encoding::to_string(), kcenon::pacs::core::dicom_element::vr(), kcenon::pacs::encoding::write_be16(), and kcenon::pacs::encoding::write_be32().

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_big_endian_codec::encode_sequence ( std::vector< uint8_t > & buffer, const core::dicom_element & element )

staticprivate

Definition at line 214 of file explicit_vr_big_endian_codec.cpp.

                                      {
    // Write reserved bytes for SQ VR (uses 32-bit length)
    write_be16(buffer, 0x0000);
 
    // Write undefined length for sequence (big-endian)
    write_be32(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 (big-endian for tag and length)
    write_be16(buffer, ITEM_GROUP);
    write_be16(buffer, SEQ_DELIM_ELEMENT);
    write_be32(buffer, 0);  // Length is always 0 for delimiter
}

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

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_big_endian_codec::encode_sequence_item ( std::vector< uint8_t > & buffer, const core::dicom_dataset & item )

staticprivate

Definition at line 235 of file explicit_vr_big_endian_codec.cpp.

                                   {
    // Write Item tag (big-endian)
    write_be16(buffer, ITEM_GROUP);
    write_be16(buffer, ITEM_TAG_ELEMENT);
 
    // Encode item content first to determine length
    auto item_content = encode(item);
 
    // Write item length (big-endian)
    write_be32(buffer, static_cast<uint32_t>(item_content.size()));
 
    // Write item content
    buffer.insert(buffer.end(), item_content.begin(), item_content.end());
}

References encode(), kcenon::pacs::encoding::write_be16(), and kcenon::pacs::encoding::write_be32().

Referenced by encode_sequence().

Here is the call graph for this function:

Here is the caller graph for this function:

from_big_endian()

std::vector< uint8_t > kcenon::pacs::encoding::explicit_vr_big_endian_codec::from_big_endian ( vr_type vr, std::span< const uint8_t > data )

staticnodiscard

Convert element value from big-endian to little-endian.

Parameters

vr	The VR type of the element
data	The big-endian data to convert

Returns

Little-endian encoded data

Performs the inverse of to_big_endian().

Definition at line 150 of file explicit_vr_big_endian_codec.cpp.

                                             {
    // Byte swapping is symmetric - same operation in both directions
    return to_big_endian(vr, data);
}

References to_big_endian(), and vr.

Referenced by decode_element(), and decode_undefined_length().

Here is the call graph for this function:

Here is the caller graph for this function:

to_big_endian()

std::vector< uint8_t > kcenon::pacs::encoding::explicit_vr_big_endian_codec::to_big_endian ( vr_type vr, std::span< const uint8_t > data )

staticnodiscard

Convert element value from little-endian to big-endian.

Parameters

vr	The VR type of the element
data	The little-endian data to convert

Returns

Big-endian encoded data

Performs byte swapping based on VR type:

• US/SS: 16-bit swap
• UL/SL/FL/AT: 32-bit swap
• FD: 64-bit swap
• OW: 16-bit word swap for each word
• OL/OF: 32-bit swap for each value
• OD: 64-bit swap for each value
• String VRs: No swap needed

Definition at line 132 of file explicit_vr_big_endian_codec.cpp.

                                             {
    if (!requires_byte_swap(vr) || data.empty()) {
        return {data.begin(), data.end()};
    }
 
    switch (swap_unit_size(vr)) {
        case 2:
            return swap_ow_bytes(data);
        case 4:
            return swap_ol_bytes(data);
        case 8:
            return swap_od_bytes(data);
        default:
            return {data.begin(), data.end()};
    }
}

References kcenon::pacs::encoding::swap_od_bytes(), kcenon::pacs::encoding::swap_ol_bytes(), kcenon::pacs::encoding::swap_ow_bytes(), and vr.

Referenced by encode_element(), and from_big_endian().

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_big_endian_codec.h
• src/encoding/explicit_vr_big_endian_codec.cpp