Metadata-Version: 2.2
Name: cube-compress
Version: 0.1.0
Summary: Compress and decompress Gaussian CUBE files using 24-bit float packing.
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# cube_compress.py

一个用于将 Gaussian CUBE 体数据文件压缩为 `.cubexs`，并可解压回 `.cube` 的小工具。核心思路是把 `float32` 数据压缩为 24-bit（1 位符号 + 8 位指数 + 15 位尾数），再用 gzip 进行二次压缩。

## 依赖

- Python 3.x
- numpy

> `gzip` 为 Python 标准库，无需额外安装。

## 功能概览

- `float32_to_24bit(data_array)`  
  将 `float32` 数组压缩为 24-bit（3 字节）表示。

- `uint8_from_24bit(byte_array, num_values)`  
  将 24-bit 数据还原为 `float32` 数组。

- `compress(input_file, output_file)`  
  读取 `.cube` 文件，压缩数据并写入 `.cubexs`。

- `decompress(input_file, output_file)`  
  读取 `.cubexs` 文件，解压并输出 `.cube`。

## 使用示例

```python
from cube_compress import compress, decompress, compress_cube_file

# 压缩
compress("input.cube", "output.cubexs")

# 解压
decompress("output.cubexs", "restored.cube")

```

## 安装（本地开发）

在项目根目录执行：

```bash
pip install -e .
```

然后即可通过 `import cube_compress` 使用。

## 文件结构说明

`.cubexs` 的结构为：

1. 原 `.cube` 的头部文本（UTF-8，逐行写入）
2. 三行元数据：
   - `compressed_size=...`
   - `original_size=...`
   - `num_values=...`
3. gzip 压缩后的二进制数据（24-bit 数据重排后压缩）

## 注意事项

- 该压缩是**有损**的（尾数从 23 位缩减为 15 位）。
- `.cube` 文件头部必须符合标准格式（前几行标题、Fermi 信息、原子数与网格信息）。
