NDimensionalContainer.hpp

Go to the documentation of this file.

#pragma once
 
#include "NDData/NDData.hpp"
 
namespace MayaFlux::Kakshya {
 
/**
 * @brief Forward declarations for region structures used in N-dimensional data containers.
 */
struct Region;
struct RegionGroup;
struct RegionSegment;
 
/**
 * @brief Container structure for consistent dimension ordering.
 *
 * Provides standard indices and layout structures for common data types,
 * supporting digital-first, data-driven workflows. These structures are
 * not tied to analog metaphors, but instead facilitate generic, flexible
 * processing of multi-dimensional data.
 */
struct MAYAFLUX_API ContainerDataStructure {
 
    // Image/Video structures
    // static constexpr size_t FRAME_DIM = 0;
    // static constexpr size_t COLOR_DIM = 3;
 
    // Spectral structures
    // static constexpr size_t TIME_WINDOW_DIM = 0;
 
    std::vector<DataDimension> dimensions;
 
    std::optional<size_t> time_dims;
    std::optional<size_t> channel_dims;
    std::optional<size_t> height_dims;
    std::optional<size_t> width_dims;
    std::optional<size_t> frequency_dims;
 
    DataModality modality {};
    MemoryLayout memory_layout = MemoryLayout::ROW_MAJOR;
    OrganizationStrategy organization = OrganizationStrategy::PLANAR;
 
    /**
     * @brief Construct a container structure with specified parameters.
     * @param mod Data modality type
     * @param org Organization strategy (default: PLANAR)
     * @param layout Memory layout (default: ROW_MAJOR)
     */
    ContainerDataStructure(DataModality mod,
        OrganizationStrategy org = OrganizationStrategy::PLANAR,
        MemoryLayout layout = MemoryLayout::ROW_MAJOR);
 
    ContainerDataStructure() = default;
 
    /**
     * @brief Get the expected dimension roles for this structure's modality.
     * @return Vector of dimension roles in order
     */
    [[nodiscard]] std::vector<DataDimension::Role> get_expected_dimension_roles() const;
 
    /**
     * @brief Create structure for planar audio data.
     * @return Containerstructure configured for planar audio
     */
    static ContainerDataStructure audio_planar();
 
    /**
     * @brief Create structure for interleaved audio data.
     * @return Containerstructure configured for interleaved audio
     */
    static ContainerDataStructure audio_interleaved();
 
    /**
     * @brief Create structure for planar image data.
     * @return Containerstructure configured for planar images
     */
    static ContainerDataStructure image_planar();
 
    /**
     * @brief Create structure for interleaved image data.
     * @return Containerstructure configured for interleaved images
     */
    static ContainerDataStructure image_interleaved();
 
    /**
     * @brief Calculate expected number of data variants for given dimensions.
     * @param dimensions Vector of dimension descriptors
     * @return Expected number of DataVariant objects needed
     */
    [[nodiscard]] size_t get_expected_variant_count(const std::vector<DataDimension>& dimensions) const;
 
    /**
     * @brief Calculate size of a specific variant in the organization.
     * @param dimensions Vector of dimension descriptors
     * @param modality Data modality type
     * @param organization Organization strategy
     * @param variant_index Index of the variant (0-based)
     * @return Number of elements in the specified variant
     */
    [[nodiscard]] static uint64_t get_variant_size(const std::vector<DataDimension>& dimensions,
        DataModality modality, OrganizationStrategy organization, size_t variant_index = 0);
    [[nodiscard]] uint64_t get_variant_size() const { return get_variant_size(dimensions, modality, organization); }
 
    /**
     * @brief Validate that dimensions match this structure's expectations.
     * @param dimensions Vector of dimension descriptors to validate
     * @return true if dimensions are valid for this structure
     */
    [[nodiscard]] bool validate_dimensions(const std::vector<DataDimension>& dimensions) const;
 
    /**
     * @brief Find the index of a dimension with the specified role.
     * @param dimensions Vector of dimension descriptors to search
     * @param role Dimension role to find
     * @return Index of the dimension with the specified role
     */
    [[nodiscard]] size_t get_dimension_index_for_role(const std::vector<DataDimension>& dimensions,
        DataDimension::Role role) const;
 
    /**
     * @brief Get total elements across all dimensions.
     * @param dimensions Vector of dimension descriptors
     * @return Total number of elements
     */
    [[nodiscard]] static uint64_t get_total_elements(const std::vector<DataDimension>& dimensions);
    [[nodiscard]] uint64_t get_total_elements() const { return get_total_elements(dimensions); }
 
    /**
     * @brief Get total number of components (channels, spatial, frequency).
     * @param dimensions Vector of dimension descriptors
     * @return Total number of components
     */
    [[nodiscard]] static uint64_t get_component_count(const std::vector<DataDimension>& dimensions);
    [[nodiscard]] uint64_t get_component_count() const { return get_component_count(dimensions); }
 
    /**
     * @brief Extract sample count from dimensions.
     * @param dimensions Vector of dimension descriptors
     * @return Number of samples in the temporal dimension
     */
    [[nodiscard]] static uint64_t get_samples_count(const std::vector<DataDimension>& dimensions);
    [[nodiscard]] uint64_t get_samples_count() const { return get_samples_count(dimensions); }
 
    /**
     * @brief Get samples per channel (time dimension only).
     * @param dimensions Vector of dimension descriptors
     * @return Number of samples per channel
     */
    [[nodiscard]] static uint64_t get_samples_count_per_channel(const std::vector<DataDimension>& dimensions);
    [[nodiscard]] uint64_t get_samples_count_per_channel() const { return get_samples_count_per_channel(dimensions); }
 
    /**
     * @brief Extract channel count from dimensions.
     * @param dimensions Vector of dimension descriptors
     * @return Number of channels
     */
    [[nodiscard]] static uint64_t get_channel_count(const std::vector<DataDimension>& dimensions);
    [[nodiscard]] uint64_t get_channel_count() const { return get_channel_count(dimensions); }
 
    /**
     * @brief Get pixel count (spatial dimensions only).
     * @param dimensions Vector of dimension descriptors
     * @return Number of pixels
     */
    [[nodiscard]] static uint64_t get_pixels_count(const std::vector<DataDimension>& dimensions);
    [[nodiscard]] uint64_t get_pixels_count() const { return get_pixels_count(dimensions); }
 
    /**
     * @brief Extract height from image/video dimensions.
     * @param dimensions Vector of dimension descriptors
     * @return Height in pixels
     */
    [[nodiscard]] static uint64_t get_height(const std::vector<DataDimension>& dimensions);
    [[nodiscard]] uint64_t get_height() const { return get_height(dimensions); }
 
    /**
     * @brief Extract width from image/video dimensions.
     * @param dimensions Vector of dimension descriptors
     * @return Width in pixels
     */
    [[nodiscard]] static uint64_t get_width(const std::vector<DataDimension>& dimensions);
    [[nodiscard]] uint64_t get_width() const { return get_width(dimensions); }
 
    /**
     * @brief Extract frame count from video dimensions.
     * @param dimensions Vector of dimension descriptors
     * @return Number of frames
     */
    [[nodiscard]] static size_t get_frame_count(const std::vector<DataDimension>& dimensions);
    [[nodiscard]] size_t get_frame_count() const { return get_frame_count(dimensions); }
 
    /**
     * @brief Extract the size of non time dimensions (channel, spatial, frequency)
     * @param dimensions Vector of dimension descriptors
     * @return cumulative size of non time dimensions
     */
    [[nodiscard]] static size_t get_frame_size(const std::vector<DataDimension>& dimensions);
    [[nodiscard]] size_t get_frame_size() const { return get_frame_size(dimensions); }
};
 
/**
 * @class NDDataContainer
 * @brief Abstract interface for N-dimensional data containers.
 *
 * NDDataContainer provides a dimension-agnostic API for accessing and manipulating
 * multi-dimensional data (audio, video, tensors, etc). It is designed for digital-first,
 * data-driven workflows, enabling flexible, efficient, and generic processing of
 * structured data without imposing analog metaphors or legacy constraints.
 *
 * Key features:
 * - Arbitrary dimension support (not limited to 2D or 3D)
 * - Explicit memory layout control (row-major/column-major)
 * - Region-based access for efficient subsetting and streaming
 * - Thread-safe locking for concurrent processing
 * - Support for multiple data types and precisions
 * - Designed for composability with processors, buffers, and computational nodes
 *
 * This interface is the foundation for all high-level data containers in Maya Flux,
 * enabling advanced workflows such as real-time streaming, offline analysis, and
 * hybrid computational models.
 */
class MAYAFLUX_API NDDataContainer {
public:
    virtual ~NDDataContainer() = default;
 
    /**
     * @brief Get the dimensions describing the structure of the data.
     * @return Vector of DataDimension objects (one per axis)
     */
    [[nodiscard]] virtual std::vector<DataDimension> get_dimensions() const = 0;
 
    /**
     * @brief Get the total number of elements in the container.
     * @return Product of all dimension sizes
     */
    [[nodiscard]] virtual uint64_t get_total_elements() const = 0;
 
    /**
     * @brief Get the memory layout used by this container.
     * @return Current memory layout (row-major or column-major)
     */
    [[nodiscard]] virtual MemoryLayout get_memory_layout() const = 0;
 
    /**
     * @brief Set the memory layout for this container.
     * @param layout New memory layout to use
     * @note May trigger data reorganization if implementation supports both layouts
     */
    virtual void set_memory_layout(MemoryLayout layout) = 0;
 
    /**
     * @brief Get the number of elements that constitute one "frame".
     * For audio: channels per sample. For images: pixels per frame.
     * @return Number of elements per frame
     */
    [[nodiscard]] virtual uint64_t get_frame_size() const = 0;
 
    /**
     * @brief Get the number of frames in the primary (temporal) dimension.
     * @return Number of frames
     */
    [[nodiscard]] virtual uint64_t get_num_frames() const = 0;
 
    /**
     * @brief Get data for a specific region.
     * @param region The region to extract data from
     * @return std::vector<DataVariant> containing the region's data
     */
    [[nodiscard]] virtual std::vector<DataVariant> get_region_data(const Region& region) const = 0;
 
    /**
     * @brief Get data for multiple regions efficiently.
     * @param regions Vector of regions to extract data from
     * @return Vector of DataVariant vectors, one per region
     */
    [[nodiscard]] virtual std::vector<DataVariant> get_region_group_data(const RegionGroup& regions) const = 0;
 
    /**
     * @brief Get data for multiple region segments efficiently.
     * @param segments Vector of region segments to extract data from
     * @return Vector of DataVariant vectors, one per segment
     */
    [[nodiscard]] virtual std::vector<DataVariant> get_segments_data(const std::vector<RegionSegment>& segments) const = 0;
 
    /**
     * @brief Set data for a specific region.
     * @param region The region to write data to
     * @param data The data to write
     */
    virtual void set_region_data(const Region& region, const std::vector<DataVariant>& data) = 0;
 
    /**
     * @brief Get a single frame of data efficiently.
     * @param frame_index Index of the frame (in the temporal dimension)
     * @return Span of data representing one complete frame
     */
    [[nodiscard]] auto get_frame(uint64_t frame_index) const -> FrameView
    {
        return FrameView(get_frame_span_impl(frame_index));
    }
 
    /**
     * @brief Get multiple frames efficiently.
     * @param output Buffer to write frames into
     * @param start_frame First frame index
     * @param num_frames Number of frames to retrieve
     */
    template <DataVariantElement T>
    void get_frames(std::span<T> output, uint64_t start_frame, uint64_t num_frames) const
    {
        get_frames_impl(output.data(), output.size(), start_frame, num_frames, typeid(T));
    }
 
    /**
     * @brief Get a single frame of data as a typed span.
     * @tparam T Element type to interpret the frame data as
     * @param frame_index Index of the frame (in the temporal dimension)
     * @return Span of data representing one complete frame, interpreted as type T
     */
    template <DataVariantElement T>
    [[nodiscard]] auto get_frame_as(uint64_t frame_index) const -> std::span<const T>
    {
        return get_frame(frame_index).template as<T>();
    }
 
    /**
     * @brief Get multiple frames efficiently as a typed span.
     *
     * Convenience wrapper over get_frames() for callers that know the element
     * type statically but hold the output buffer as a plain vector rather than
     * a typed span. Deduces T from the vector element type; no visitor, no
     * type query needed at the call site.
     *
     * @tparam T Element type. Must satisfy DataVariantElement and match the
     *           container's native element type. The impl silently no-ops or
     *           errors on mismatch depending on the container.
     * @param output      Destination vector. Resized to num_frames * frame_size
     *                    by the caller before passing; content is overwritten.
     * @param start_frame First frame index.
     * @param num_frames  Number of frames to retrieve.
     */
    template <DataVariantElement T>
    void get_frames_as(std::vector<T>& output, uint64_t start_frame, uint64_t num_frames) const
    {
        get_frames_impl(output.data(), output.size(), start_frame, num_frames, typeid(T));
    }
 
    /**
     * @brief Runtime query for the native scalar element type of this container.
     *
     * Mirrors FrameView::element_type(). Typical return values:
     * - typeid(uint8_t)  -- 8-bit image / video / window
     * - typeid(uint16_t) -- 16-bit image
     * - typeid(float)    -- HDR image
     * - typeid(double)   -- audio / plot
     *
     * Use this to branch once before calling get_value_at<T>() when the
     * container's native type is not statically known at the call site.
     */
    [[nodiscard]] virtual std::type_index value_element_type() const = 0;
 
    /**
     * @brief Read a single element at the given N-dimensional coordinates.
     *
     * Returns a default-constructed T on coordinate out-of-range or type mismatch.
     * No conversion is performed: T must match the container's native element type
     * (query value_element_type() first when the type is not statically known).
     *
     * @tparam T Element type. Must satisfy DataVariantElement.
     * @param coordinates N-dimensional coordinate vector.
     * @return Native-typed value, zero-initialised on error.
     */
    template <DataVariantElement T>
    [[nodiscard]] T get_value_at(const std::vector<uint64_t>& coordinates) const
    {
        T v {};
        get_value_impl(coordinates, &v, typeid(T));
        return v;
    }
 
    /**
     * @brief Write a single element at the given N-dimensional coordinates.
     *
     * No-ops on coordinate out-of-range or type mismatch.
     * T must match the container's native element type.
     *
     * @tparam T Element type. Must satisfy DataVariantElement.
     * @param coordinates N-dimensional coordinate vector.
     * @param value       Value to write.
     */
    template <DataVariantElement T>
    void set_value_at(const std::vector<uint64_t>& coordinates, T value)
    {
        set_value_impl(coordinates, &value, typeid(T));
    }
 
    /**
     * @brief Add a named group of regions to the container.
     * @param group RegionGroup to add
     */
    virtual void add_region_group(const RegionGroup& group) = 0;
 
    /**
     * @brief Get a region group by name.
     * @param name Name of the region group
     * @return Reference to the RegionGroup
     */
    [[nodiscard]] virtual RegionGroup get_region_group(const std::string& name) const = 0;
 
    /**
     * @brief Get all region groups in the container.
     * @return Map of region group names to RegionGroup objects
     */
    [[nodiscard]] virtual std::unordered_map<std::string, RegionGroup> get_all_region_groups() const = 0;
 
    /**
     * @brief Remove a region group by name.
     * @param name Name of the region group to remove
     */
    virtual void remove_region_group(const std::string& name) = 0;
 
    /**
     * @brief Check if a region is loaded in memory.
     * @param region Region to check
     * @return true if region is loaded, false otherwise
     */
    [[nodiscard]] virtual bool is_region_loaded(const Region& region) const = 0;
 
    /**
     * @brief Load a region into memory.
     * @param region Region to load
     */
    virtual void load_region(const Region& region) = 0;
 
    /**
     * @brief Unload a region from memory.
     * @param region Region to unload
     */
    virtual void unload_region(const Region& region) = 0;
 
    /**
     * @brief Convert coordinates to linear index based on current memory layout.
     * @param coordinates N-dimensional coordinates
     * @return Linear index into the underlying data storage
     */
    [[nodiscard]] virtual uint64_t coordinates_to_linear_index(const std::vector<uint64_t>& coordinates) const = 0;
 
    /**
     * @brief Convert linear index to coordinates based on current memory layout.
     * @param linear_index Linear index into the underlying data storage
     * @return N-dimensional coordinates
     */
    [[nodiscard]] virtual std::vector<uint64_t> linear_index_to_coordinates(uint64_t linear_index) const = 0;
 
    /**
     * @brief Clear all data in the container.
     */
    virtual void clear() = 0;
 
    /**
     * @brief Get a raw pointer to the underlying data storage.
     * @return Pointer to raw data (type depends on DataVariant)
     */
    [[nodiscard]] virtual const void* get_raw_data() const = 0;
 
    /**
     * @brief Check if the container currently holds any data.
     * @return true if data is present, false otherwise
     */
    [[nodiscard]] virtual bool has_data() const = 0;
 
    /**
     * @brief Get the data structure defining this container's layout.
     * @return Reference to the ContainerDataStructure
     */
    [[nodiscard]] virtual ContainerDataStructure& get_structure() = 0;
    [[nodiscard]] virtual const ContainerDataStructure& get_structure() const = 0;
 
    /**
     * @brief Set the data structure for this container.
     * @param structure New ContainerDataStructure to apply
     * @note This may trigger reorganization of existing data to match the new structure.
     */
    virtual void set_structure(ContainerDataStructure structure) = 0;
 
protected:
    /**
     * @brief Implementation-specific method to retrieve a frame span.
     * @param frame_index Index of the frame to retrieve
     * @return DataSpanVariant representing the frame's data
     */
    [[nodiscard]] virtual auto get_frame_span_impl(uint64_t frame_index) const -> DataSpanVariant = 0;
 
    /**
     * @brief Implementation-specific method to retrieve multiple frames.
     *
     * Implementations write up to count * frame_size elements into output,
     * starting from start_frame. The type parameter indicates the expected
     * element type; implementations may choose to support or reject it based
     * on their native data type, but must not write past the output buffer
     * regardless.
     *
     * @param output Pointer to caller-owned buffer for frame data
     * @param count Number of frames to retrieve (output buffer size in frames)
     * @param start_frame First frame index to retrieve
     * @param num_frames Number of frames to retrieve
     * @param type Type information for the expected element type (e.g. float, uint8_t)
     */
    virtual void get_frames_impl(void* output, size_t count, uint64_t start_frame, uint64_t num_frames, const std::type_info& type) const = 0;
 
    /**
     * @brief Type-erased single-element read.
     *
     * Implementations copy the native element at @p coords into @p out
     * if @p type matches their native type, otherwise no-op.
     * @p out points to a caller-owned buffer of exactly sizeof(native type) bytes.
     */
    virtual void get_value_impl(const std::vector<uint64_t>& coords,
        void* out,
        const std::type_info& type) const = 0;
 
    /**
     * @brief Type-erased single-element write.
     *
     * Implementations copy from @p in into their storage at @p coords
     * if @p type matches their native type, otherwise no-op.
     * @p in points to a caller-owned buffer of exactly sizeof(native type) bytes.
     */
    virtual void set_value_impl(const std::vector<uint64_t>& coords,
        const void* in,
        const std::type_info& type) = 0;
};
 
} // namespace MayaFlux::Kakshya