API‐Reference

C++ Core API & C-ABI Reference

This document defines the primary C++ interfaces and cross-language C-ABI bindings for SpaceEntropyCompression (SEC).

---

1. C++ Core API

All core types reside within the namespace sec.

Encoder Interface

namespace sec {

struct Config {
    uint8_t  dimension = 3;             // 3D or 4D coordinate space
    uint8_t  coord_bit_depth = 16;      // Quantization bits (10, 16, 21, 32)
    float    error_bound = 1e-4f;       // Max allowable point-to-point error
    bool     lossless = false;          // Lossless vs Bounded-Lossy mode
    bool     include_tensors = false;   // Compress metric curvature tensors
};

struct BufferView {
    const uint8_t* data;
    size_t         size_bytes;
};

// Main entry point for spatial point cloud encoding
BufferView CompressPointCloud(
    const float* coords_xyz,
    size_t       point_count,
    const Config& config,
    uint8_t*     out_buffer,
    size_t       out_buffer_capacity
);

// Decodes a complete .sec container into contiguous coordinate arrays
size_t DecompressPointCloud(
    const uint8_t* sec_data,
    size_t         sec_data_size,
    float*         out_coords_xyz,
    size_t         max_points
);

} // namespace sec

---

2. Low-Level Chunk API

For parallel chunk streaming and network ingestion:

namespace sec {

// Processes a single independent spatial chunk
size_t DecompressChunk(
    const SECChunkHeader* header,
    const uint8_t*        payload,
    uint32_t*             out_coords_x,
    uint32_t*             out_coords_y,
    uint32_t*             out_coords_z,
    uint16_t*             out_vci
);

} // namespace sec

---

3. C-ABI Bindings (sec_capi.h)

For integration into Python, Julia, C#, and Fortran astrophysical workflows:

#ifdef __cplusplus
extern "C" {
#endif

typedef struct {
    uint8_t  dimension;
    uint8_t  bit_depth;
    float    error_bound;
    int32_t  is_lossless;
} sec_c_config_t;

SEC_API int32_t sec_compress(
    const float* in_coords,
    uint64_t     count,
    const sec_c_config_t* config,
    uint8_t*     out_buf,
    uint64_t     out_capacity,
    uint64_t*    bytes_written
);

SEC_API int32_t sec_decompress(
    const uint8_t* in_buf,
    uint64_t       in_size,
    float*         out_coords,
    uint64_t       max_points,
    uint64_t*      points_read
);

#ifdef __cplusplus
}
#endif