Metadata-Version: 2.4
Name: FracDimPy
Version: 0.1.0
Summary: A comprehensive Python package for fractal dimension calculation and multifractal analysis
Home-page: https://github.com/songLe/FracDimPy
Author: SONG-LE
Author-email: SONG-LE <3590453833@qq.com>
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/songLe/FracDimPy
Project-URL: Documentation, https://github.com/songLe/FracDimPy/blob/main/README.md
Project-URL: Repository, https://github.com/songLe/FracDimPy
Project-URL: Issues, https://github.com/songLe/FracDimPy/issues
Keywords: fractal,fractal dimension,multifractal,box-counting,Hurst,R/S analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: pandas>=1.3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=5.0; extra == "dev"
Requires-Dist: mypy>=0.990; extra == "dev"
Provides-Extra: full
Requires-Dist: opencv-python>=4.5.0; extra == "full"
Requires-Dist: Pillow>=9.0.0; extra == "full"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# FracDimPy

<div align="center">

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Version](https://img.shields.io/badge/version-0.1.0-green.svg)](https://github.com/songLe/FracDimPy)

**一个全面的Python分形维数计算与多重分形分析工具包**

[English](README_EN.md) | 简体中文

</div>

---

## 📖 简介

FracDimPy 是一个功能强大、易于使用的Python软件包，专门用于分形维数计算和多重分形分析。无论您是研究分形几何的科研人员，还是需要分析复杂数据的工程师，FracDimPy都能为您提供专业、准确的分析工具。

### ✨ 主要特性

- **🔢 多种单分形方法**
  - Hurst指数法 (R/S分析)
  - 盒计数法 (Box-counting)
  - 信息维数法 (Information Dimension)
  - 关联维数法 (Correlation Dimension)
  - 结构函数法 (Structure Function)
  - 变差函数法 (Variogram)
  - 沙盒法 (Sandbox)
  - 去趋势波动分析 (DFA)

- **📊 多重分形分析**
  - 一维曲线多重分形分析
  - 二维图像多重分形分析
  - 多重分形去趋势波动分析 (MF-DFA)
  - 自定义尺度序列

- **🎨 分形生成器**
  - 经典分形：Cantor集、Sierpinski三角形/地毯、Koch曲线、Menger海绵等
  - 随机分形：布朗运动、Lévy飞行、自回避行走、扩散限制聚集(DLA)
  - 分形曲线：FBM曲线、Weierstrass-Mandelbrot函数、Takagi曲线
  - 分形曲面：FBM曲面、Weierstrass-Mandelbrot曲面、Takagi曲面

- **📈 丰富的可视化**
  - 自动生成专业图表
  - 双对数图拟合
  - 多重分形谱展示
  - 可定制的绘图选项

- **💾 灵活的数据处理**
  - 支持多种数据格式 (CSV, Excel, TXT, NPY, 图像等)
  - 自动数据预处理
  - 结果导出功能

---

## 🚀 快速开始

### 安装

#### 从PyPI安装（推荐）

```bash
# 基础安装
pip install FracDimPy

# 完整安装（包含所有可选依赖）
pip install FracDimPy[full]
```

#### 从源码安装

```bash
git clone https://github.com/songLe/FracDimPy.git
cd FracDimPy
pip install -e .
```

详细安装说明请参阅 [INSTALLATION.md](INSTALLATION.md)

### 基本使用

#### 示例1：计算时间序列的Hurst指数

```python
import numpy as np
from fracDimPy import hurst_dimension

# 生成测试数据
data = np.random.randn(1000).cumsum()

# 计算Hurst指数
D, result = hurst_dimension(data, method='RS', show_plot=True)

print(f"分形维数: {D:.4f}")
print(f"Hurst指数: {result['H']:.4f}")
```

#### 示例2：盒计数法分析图像

```python
from fracDimPy import box_counting
import matplotlib.pyplot as plt
import matplotlib.image as mpimg

# 读取图像
img = mpimg.imread('fractal_image.png')

# 计算分形维数
D, result = box_counting(img, show_plot=True)

print(f"盒计数维数: {D:.4f}")
print(f"拟合优度 R²: {result['r_squared']:.4f}")
```

#### 示例3：多重分形分析

```python
from fracDimPy import multifractal_curve
import numpy as np

# 读取数据
data = np.loadtxt('curve_data.txt')

# 多重分形分析
result = multifractal_curve(
    data,
    q_range=(-10, 10),
    show_plot=True,
    save_path='mf_result.png'
)

print(f"多重分形谱宽度 Δα: {result['delta_alpha']:.4f}")
print(f"奇异性强度 Δf: {result['delta_f']:.4f}")
```

#### 示例4：生成分形图案

```python
from fracDimPy import generate_sierpinski, generate_koch_snowflake
import matplotlib.pyplot as plt

# 生成Sierpinski三角形
sierpinski = generate_sierpinski(level=6)

# 生成Koch雪花
snowflake = generate_koch_snowflake(level=5)

# 可视化
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 6))
ax1.scatter(sierpinski[:, 0], sierpinski[:, 1], s=1, c='blue')
ax1.set_title('Sierpinski Triangle')
ax1.axis('equal')

ax2.plot(snowflake[:, 0], snowflake[:, 1], 'r-', linewidth=0.5)
ax2.set_title('Koch Snowflake')
ax2.axis('equal')

plt.show()
```

---

## 📚 文档目录

- [安装指南](INSTALLATION.md) - 详细的安装说明
- [构建指南](BUILD.md) - 从源码构建的说明
- [贡献指南](CONTRIBUTING.md) - 如何为项目做贡献
- [更新日志](CHANGELOG.md) - 版本更新记录
- [示例代码](examples/) - 丰富的使用示例

---

## 📦 模块说明

### 1. 单分形模块 (`monofractal`)

提供多种单分形维数计算方法：

| 方法 | 函数名 | 适用数据类型 | 说明 |
|------|--------|--------------|------|
| Hurst指数 | `hurst_dimension()` | 1D时间序列 | R/S分析、修正R/S、DFA |
| 盒计数法 | `box_counting()` | 1D/2D/3D | 最常用的分形维数计算方法 |
| 信息维数 | `information_dimension()` | 点集数据 | 基于信息熵的维数 |
| 关联维数 | `correlation_dimension()` | 点集数据 | 基于关联积分 |
| 结构函数 | `structural_function()` | 1D曲线 | 适用于自仿射曲线 |
| 变差函数 | `variogram_method()` | 1D/2D | 地统计学方法 |
| 沙盒法 | `sandbox_method()` | 点集/图像 | 局部尺度分析 |
| DFA | `dfa()` | 1D时间序列 | 去趋势波动分析 |

### 2. 多重分形模块 (`multifractal`)

提供多重分形分析工具：

| 函数 | 说明 | 输出 |
|------|------|------|
| `multifractal_curve()` | 一维曲线多重分形分析 | 配分函数、广义维数、多重分形谱 |
| `multifractal_image()` | 二维图像多重分形分析 | 奇异性指数、多重分形特征 |
| `mf_dfa()` | 多重分形DFA | 波动函数、Hurst指数谱 |

### 3. 分形生成器 (`generator`)

生成各种理论和随机分形：

**曲线类** (1D):
- `generate_fbm_curve()` - 分数布朗运动曲线
- `generate_wm_curve()` - Weierstrass-Mandelbrot函数
- `generate_takagi_curve()` - Takagi曲线
- `generate_koch_curve()` - Koch曲线
- `generate_brownian_motion()` - 布朗运动
- `generate_levy_flight()` - Lévy飞行

**曲面类** (2D):
- `generate_fbm_surface()` - 分数布朗运动曲面
- `generate_wm_surface()` - WM曲面
- `generate_takagi_surface()` - Takagi曲面

**图案类** (几何分形):
- `generate_cantor_set()` - Cantor集
- `generate_sierpinski()` - Sierpinski三角形
- `generate_sierpinski_carpet()` - Sierpinski地毯
- `generate_vicsek_fractal()` - Vicsek分形
- `generate_koch_snowflake()` - Koch雪花
- `generate_dla()` - 扩散限制聚集
- `generate_menger_sponge()` - Menger海绵（3D）

### 4. 工具模块 (`utils`)

- 数据读写 (`data_io`)
- 可视化工具 (`plotting`)

---

## 🔬 应用领域

FracDimPy可应用于多个科学和工程领域：

- **地球科学**：地形分析、地震数据、裂缝网络
- **材料科学**：多孔介质、表面粗糙度、纳米结构
- **生物医学**：DNA序列、蛋白质折叠、医学影像
- **金融分析**：股票价格、市场波动、风险评估
- **图像处理**：纹理分析、模式识别、图像分割
- **环境科学**：河流网络、云图分析、污染扩散
- **物理学**：湍流、相变、混沌系统

---

## 📊 示例与数据

[examples](examples/) 目录包含丰富的示例代码和测试数据：

```
examples/
├── monofractal/          # 单分形方法示例
│   ├── test_hurst.py
│   ├── test_box_counting_*.py
│   └── ...
├── multifractal/         # 多重分形示例
│   ├── test_mf_curve_*.py
│   ├── test_mf_image.py
│   └── ...
└── generator/            # 分形生成示例
    ├── test_koch.py
    ├── test_dla.py
    └── ...
```

运行示例：

```bash
cd examples/monofractal
python test_hurst.py
```

详见 [examples/README.md](examples/README.md)

---

## 🛠️ 依赖项

### 核心依赖
- Python >= 3.8
- NumPy >= 1.20.0
- SciPy >= 1.7.0
- Matplotlib >= 3.3.0
- Pandas >= 1.3.0

### 可选依赖
- `opencv-python` - 高级图像处理
- `Pillow` - 图像读写

完整依赖列表请参阅 [pyproject.toml](pyproject.toml)

---

## 🤝 贡献

欢迎各种形式的贡献！无论是报告bug、提出新功能建议，还是提交代码改进。

请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细的贡献指南。

### 贡献者

- **SONG-LE** - *主要开发者* - [知乎主页](https://www.zhihu.com/people/xiao-xue-sheng-ye-xiang-xie-shu/posts)

---

## 📄 许可证

本项目采用 GNU General Public License v3.0 许可证 - 详见 [LICENSE](LICENSE) 文件

---

## 📮 联系方式

- **作者**: SONG-LE
- **邮箱**: 3590453833@qq.com
- **知乎**: [小学生也想写书](https://www.zhihu.com/people/xiao-xue-sheng-ye-xiang-xie-shu/posts)
- **GitHub**: [https://github.com/songLe/FracDimPy](https://github.com/songLe/FracDimPy)

---

## 📝 引用

如果您在研究中使用了FracDimPy，请引用：

```bibtex
@software{fracdimpy2024,
  author = {SONG-LE},
  title = {FracDimPy: A Comprehensive Python Package for Fractal Dimension Calculation and Multifractal Analysis},
  year = {2024},
  url = {https://github.com/songLe/FracDimPy},
  version = {0.1.0}
}
```

---

## 🙏 致谢

感谢所有为分形理论和算法实现做出贡献的研究者和开源社区成员。

---

## ⭐ Star History

如果这个项目对您有帮助，请给它一个⭐️！

---

## 🔗 相关项目

- [NumPy](https://numpy.org/) - 数值计算基础
- [SciPy](https://scipy.org/) - 科学计算工具
- [Matplotlib](https://matplotlib.org/) - 数据可视化

---

<div align="center">

**[⬆ 返回顶部](#fracdimpy)**

Made with ❤️ by SONG-LE

</div>

