Metadata-Version: 2.4
Name: inkhinge
Version: 1.2.2
Summary: The next-generation deep learning toolkit designed specifically for spectral analysis
Home-page: https://github.com/1412universe/inkhinge
Author: Fenglong Li,Siyang Li
Author-email: 15340666394@163.com
Project-URL: Bug Tracker, https://github.com/1412universe/inkhinge/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# inkhinge

`inkhinge`是一个专为光谱分析与生物信号数据处理设计的工具集，涵盖**光谱数据处理、ABF生物信号文件转换、曲线拟合、图像分析、峰检测与机器学习分类**六大核心能力。支持Omnic SPA光谱格式、ABF（生物信号）格式、多种图像格式的处理，提供从数据预处理（格式转换、背景校正）到高级建模（多维度拟合、峰检测、HAP-MoE深度学习分类）的完整流程支持。通过`pip install inkhinge`安装后，可便捷处理批量文件转换、高精度拟合、图像灰度分析、晶体结构插入等任务，适配科研场景中多类型数据的统一处理需求。


## 安装
```bash
pip install inkhinge
```


## 函数文档与使用方法

---

### `abf_to_csv`
读取ABF文件（生物信号常用格式，如电生理、传感器数据）并转换为CSV格式，支持单文件转换与批量处理，自动生成时间轴并适配不同版本ABF文件。

#### 参数:
- `input_path` (str): 输入路径（单个ABF文件或包含ABF文件的目录）。
- `output_path` (str, 可选): 输出路径（单文件转换时为CSV文件路径，批量转换时为目录路径），默认与输入同目录生成同名CSV。
- `recursive` (bool, 可选): 处理目录时是否递归子目录，默认`False`。

#### 返回:
- 元组 `(success_count, failure_count)`：成功转换的文件数与失败的文件数。

#### 核心功能:
- 自动判断输入类型（文件/目录），切换单文件/批量处理模式，无需手动调用不同函数。
- 内置`process_single_file`辅助函数，实现单文件全流程处理：包含输入文件存在性验证、ABF文件加载（兼容多版本pyabf）、加载后自动打印文件关键信息（版本、通道数、采样率、总数据点数）。
- 独立计算时间轴（基于采样率与总数据点，不依赖pyabf版本差异），支持最高100000 Hz采样率，生成后打印时间轴范围与数据点数，便于调试。
- 智能路径校正：输入文件不存在时会提示错误；输出路径若为目录，自动生成与ABF同名的CSV；输出目录不存在时自动创建，避免运行报错。
- 通道数据精细化处理：逐通道打印处理进度与数据长度，若通道数据与时间轴长度不匹配，自动截断过长数据或用NaN补全过短数据；兼容多版本pyabf的通道信息获取方式，保留通道名称与单位（如电压、电流）并作为CSV列名。
- 批量处理增强：递归模式下遍历所有子目录收集ABF文件，处理前统计文件总数，处理后输出“总文件数/成功数/失败数”的详细统计，单个文件转换失败不影响整体批量流程。

#### 使用方法:
```python
from inkhinge.core import abf_to_csv

# 示例1：单文件转换（ABF转CSV，指定输出路径）
success, failed = abf_to_csv(
    input_path="data/signal.abf",
    output_path="results/signal_output.csv"
)
print(f"单文件转换：成功{success}个，失败{failed}个")

# 示例2：批量转换目录中所有ABF（不递归子目录，输出到指定目录）
success, failed = abf_to_csv(
    input_path="data/abf_files/",
    output_path="results/abf_csvs/",
    recursive=False
)
print(f"批量转换：成功{success}个，失败{failed}个")

# 示例3：递归批量转换（处理子目录中所有ABF，默认输出到原目录）
success, failed = abf_to_csv(
    input_path="data/parent_dir/",
    recursive=True
)
print(f"递归批量转换：成功{success}个，失败{failed}个")
```

---

### `read_to_csv`
读取Omnic SPA格式光谱文件并转换为CSV格式，支持背景校正、批量处理及多文件合并，自动计算Kubelka-Munk（KM）值。

#### 参数:
- `input_path` (str): 输入路径（单个SPA文件或包含SPA文件的目录）。
- `output_path` (str, 可选): 输出路径（单个CSV文件或目录），默认与输入同目录并添加`_converted`后缀。
- `background_path` (str, 可选): 背景文件（如BG.spa）路径，用于背景校正（透射率/反射率数据适用）。
- `overwrite` (bool, 可选): 是否覆盖已有文件，默认`False`。
- `recursive` (bool, 可选): 处理目录时是否递归子目录，默认`False`。
- `precision` (int, 可选): 输出数据的小数位数（默认20位，确保定点表示，避免科学计数法）。
- `merge_output` (str, 可选): 合并后CSV的路径，默认`None`（不合并）。

#### 返回:
- 单个文件转换：返回输出CSV路径。
- 批量转换：返回成功转换的文件数（未合并时）或文件路径列表（合并时）。

#### 核心功能:
- 自动识别光谱类型（吸光度、透射率等）并标注单位。
- 对反射率数据自动计算Kubelka-Munk值。
- 支持背景校正（透射率数据减法校正，反射率数据除法校正）。
- 批量处理时按文件名排序，合并后列名自动编号（如`Kubelka-Munk_0`）。

#### 使用方法:
```python
from inkhinge.core import read_to_csv

# 单个SPA文件转换（带背景校正）
output_path = read_to_csv(
    input_path="sample.spa",
    output_path="output/sample.csv",
    background_path="background.BG.spa",  # 应用背景校正，无需时删除此行
    precision=15
)
print(f"转换完成，输出路径：{output_path}")

# 批量转换目录中所有SPA文件（含子目录，不合并）
success_count = read_to_csv(
    input_path="spectral_data/",
    output_path="converted_csv/",
    recursive=True,
    overwrite=True,
    precision=10
)
print(f"批量转换完成，成功转换{success_count}个文件")

# 转换并合并所有SPA文件为单个CSV
read_to_csv(
    input_path="spectral_data/",
    output_path="converted_csv/",
    merge_output="merged_spectra.csv"
)
print("转换与合并完成，结果已保存至merged_spectra.csv")
```

---

### `FindPeak_Single`
自动检测单变量信号中的显著谷值特征（适用于电流、光谱等信号），计算特征参数（谷深、面积、半高宽、信噪比、对称性等）并支持可视化。

#### 参数:
- `csv_file_path` (str): 输入CSV文件路径（包含时间列和信号列）。
- `start_row` (int, 可选): 起始行索引（从0开始），默认0。
- `end_row` (int, 可选): 结束行索引，默认`None`（读至文件末尾）。
- `max_peak_count` (int, 可选): 最多保留的事件数，默认500。
- `x_col` (str, 可选): 时间列名，默认自动识别含“time”的列。
- `y_col` (str, 可选): 信号列名，默认自动选择除时间外的第一列。
- `plot_result` (bool, 可选): 是否绘制全局检测结果图，默认`True`。
- `output_image` (str, 可选): 输出图像路径，默认`"detected_valley_features.png"`。
- `output_csv` (str, 可选): 输出事件特征CSV路径，默认`"detected_valley_features.csv"`。
- `sampling_rate` (float, 可选): 采样率（Hz），用于时间单位换算，默认1e6。
- `enable_filtering` (bool, 可选): 是否启用中值与Savgol滤波，默认`True`。
- `savgol_polyorder` (int, 可选): Savgol滤波器多项式阶数，默认3。
- `enable_outlier_removal` (bool, 可选): 是否移除离群值（基于sigma），默认`True`。
- `create_connected_peaks` (bool, 可选): 是否生成连接峰图像，默认`True`。

#### 返回:
- 字典，包含：
  - `features`: 事件特征列表，每个特征包含谷深、面积、半高宽、信噪比、对称性、上升/下降时间等。
  - `quality_metrics`: 质量指标（平均信噪比、深度变异系数等）。
  - `voltage`: 从文件名解析的电压值（若有）。
  - `connected_image_path`: 连接峰图像路径（若生成）。

#### 核心功能:
- 稳健基线估计：使用众数法（Mode）计算基线，并剔除异常值。
- 严格的筛选条件：持续时间3~200点、对称性0.1~0.55、谷深 > 1.5×基线众数、向上峰无效排除（高于基线且超过1.2×|基线|）。
- 多维度特征计算：谷深、曲线面积、半高宽、信噪比、上升/下降斜率、对称性等。
- 可视化输出：全局检测图、连接峰事件图、原始/滤波对比细节图（Top6事件）。
- 数据合理性检查：避免异常数据导致图像生成失败。

#### 使用方法:
```python
from inkhinge.core import FindPeak_Single

result = FindPeak_Single(
    csv_file_path="data/signal.csv",
    start_row=0,
    max_peak_count=300,
    output_image="detection_result.png",
    output_csv="detected_peaks.csv"
)
print(f"检测到 {len(result['features'])} 个事件")
print(f"平均信噪比: {result['quality_metrics']['avg_snr']:.2f}")
```

---

### `PeakCsv_to_Json_Down`
将峰检测生成的CSV文件（单个或多个）转换为JSON格式，用于HAP-MoE模型训练，并可选择将数据集分割为训练集和验证集。自动识别输入类型（文件/文件夹）。

#### 参数:
- `input_path` (str): 输入路径（单个CSV文件或包含CSV文件的文件夹）。
- `output_folder` (str, 可选): 输出文件夹路径，默认使用输入文件所在目录或输入文件夹。
- `output_filename` (str, 可选): 输出的完整数据集JSON文件名，默认`"processed_valleys_data.json"`。
- `use_filename_as_class` (bool, 可选): 是否从文件名中提取类别标签，默认`True`。
- `split_train_val` (bool, 可选): 是否将数据集分割为训练集和验证集，默认`True`。
- `train_ratio` (float, 可选): 训练集比例（0-1），默认0.8。
- `seed` (int, 可选): 随机种子，确保结果可复现，默认42。
- `stratify_by_class` (bool, 可选): 分割时是否按类别分层抽样，保持类别分布，默认`True`。

#### 返回:
- 字典，包含：
  - `success` (bool): 处理是否成功。
  - `total_records` (int): 生成的记录总数。
  - `output_file` (str): 完整数据集的JSON文件路径。
  - `train_file` (str, 可选): 训练集JSON文件路径（如果分割）。
  - `val_file` (str, 可选): 验证集JSON文件路径（如果分割）。
  - `data` (list): 完整的JSON数据列表。

#### 核心功能:
- 自动识别输入类型：单个文件或文件夹，并相应处理。
- 鲁棒的文件解析：尝试多种编码（utf-8-sig, utf-8, gbk, latin-1）以处理不同来源的CSV文件。
- 特征清理与标准化：移除不可见字符，安全转换数值，标准化斜率（从/s到/μs）和时间（从秒到微秒）。
- 文件名类别合并：支持将同一物质的不同测量文件（如带有`_0`, `_1`后缀或时间片段）合并为同一类别。
- 构建与HAP-MoE兼容的JSON格式：包含`instruction`, `input`（特征字符串）, `output`（类别标签）。
- 可选分层分割：按类别比例将数据分割为训练集和验证集，并分别保存。
- 输出详细统计信息：包括各类别样本数、分割后分布等。

#### 使用方法:
```python
from inkhinge.core import PeakCsv_to_Json_Down

# 批量处理文件夹中的所有CSV文件，并自动分割训练/验证集
result = PeakCsv_to_Json_Down(
    input_path="data/mergedData/kongbai/kongbai_CSV",
    output_folder="data/mergedData/kongbai/kongbai_CSV",
    output_filename="processed_valleys_data.json",
    use_filename_as_class=True,
    split_train_val=True,
    train_ratio=0.8,
    seed=42,
    stratify_by_class=True
)
if result["success"]:
    print(f"完整数据集: {result['output_file']}")
    print(f"训练集: {result['train_file']}")
    print(f"验证集: {result['val_file']}")

# 处理单个CSV文件，并保存完整数据集（不分割）
result_single = PeakCsv_to_Json_Down(
    input_path="data/mergedData/kongbai/kongbai_CSV/kongbai 6.csv",
    output_folder="data/mergedData/kongbai/kongbai_CSV",
    output_filename="single_file_data.json",
    split_train_val=False
)
```

---

### `curvefit_km_t`
对指定行的KM值随时间变化进行指数曲线拟合（模型：`y = a·x^b·exp(-c·x)`），输出拟合参数、R²值及可视化结果。

#### 参数:
- `file_path` (str): 输入CSV文件路径（每行对应一个波数，每列对应一个时间点）。
- `target_row` (int, 可选): 目标行号（从1开始），默认1。
- `txt_output_path` (str, 可选): 拟合结果文本路径，默认`curvefit_km_t.txt`。
- `png_output_path` (str, 可选): 拟合图像路径，默认`curvefit_km_t.png`。
- `show_plot` (bool, 可选): 是否显示图像，默认`True`。

#### 返回:
- 字典，包含拟合参数（`a`, `b`, `c`）、R²值、原始数据及拟合表达式等。

#### 使用方法:
```python
from inkhinge.core import curvefit_km_t

# 对CSV中第3行的KM值进行时间序列拟合
result = curvefit_km_t(
    file_path="merged_spectra.csv",
    target_row=3,
    txt_output_path="time_fit_result.txt",
    png_output_path="time_fit_plot.png"
)
print(f"拟合函数表达式：{result['fit_expression']}")
print(f"拟合优度R²：{result['r_squared']:.4f}")
```

---

### `curvefit_km_wavenumber`
对指定时间点的KM值与波数进行多峰高斯-洛伦兹混合函数拟合，适用于分析特定时间下的光谱峰特征（如峰位、半宽、振幅）。

#### 参数:
- `file_path` (str): 输入CSV文件路径（每行对应一个波数，每列对应一个时间点）。
- `time_column_index` (int, 可选): 目标时间列索引（从0开始），默认1。
- `txt_output_path` (str, 可选): 拟合结果文本路径，默认`curvefit_km_wavenumber.txt`。
- `png_output_path` (str, 可选): 拟合图像路径，默认`curvefit_km_wavenumber.png`。

#### 返回:
- 字典，包含拟合参数、R²值、拟合表达式及原始数据。

#### 拟合模型:
单个峰的混合函数表达式：  
`η·(a/(1+((w-x₀)/σ)²)) + (1-η)·(a·exp(-(w-x₀)²/(2σ²)))`  
- `η`：混合系数（0≤η≤1，η=1时为纯洛伦兹峰，η=0时为纯高斯峰）
- `a`：峰振幅（信号强度）
- `x₀`：峰位（对应波数）
- `σ`：峰半宽（反映峰的尖锐程度）

#### 使用方法:
```python
from inkhinge.core import curvefit_km_wavenumber

# 对第2列（时间点）的KM值与波数进行拟合
result = curvefit_km_wavenumber(
    file_path="merged_spectra.csv",
    time_column_index=2,
    txt_output_path="wavenumber_fit_result.txt",
    png_output_path="wavenumber_fit_plot.png"
)
print(f"拟合优度R²：{result['r2']:.4f}")
```

---

### `curvefit_km_t_wavenumber`
对时间-波数-KM值三维数据进行两步拟合，构建三维模型`KM(t,w) = a(w)·t^k·exp(-c(w)·t)`（`k`为全局常数），适用于动态光谱的时空特征分析。

#### 参数:
- `file_path` (str): 输入CSV文件路径。
- `wavenumber_min` (float, 可选): 波数下限，默认1300 cm⁻¹。
- `wavenumber_max` (float, 可选): 波数上限，默认1320 cm⁻¹。
- `output_txt_path` (str, 可选): 结果文本路径，默认`curvefit.txt`。
- `output_img_path` (str, 可选): 三维拟合图像路径，默认`curvefit.png`。
- `peak_num` (int, 可选): 拟合`a(w)`和`c(w)`时的峰数量，默认3。

#### 返回:
- 字典，包含常数`k`、`a(w)`和`c(w)`的拟合参数、整体R²值及数据范围等。

#### 核心功能:
- 自动修正波数非单调问题（排序确保波数从低到高，如1300→1320 cm⁻¹）。
- 两步拟合逻辑：先通过所有波数的时间序列拟合求`k`（取`b`值均值），再固定`k`拟合`a(w)`和`c(w)`。
- 输出原始数据与拟合曲面的三维对比图，标注整体及分项R²值，直观展示拟合效果。

#### 使用方法:
```python
from inkhinge.core import curvefit_km_t_wavenumber

# 对1300-1320 cm⁻¹范围内的三维数据进行拟合
result = curvefit_km_t_wavenumber(
    file_path="merged_spectra.csv",
    wavenumber_min=1300,
    wavenumber_max=1320,
    output_txt_path="3d_fit_result.txt",
    output_img_path="3d_fit_plot.png",
    peak_num=3
)
print(f"整体拟合优度R²：{result['r2_overall']:.4f}")
print(f"全局常数k值：{result['k']:.6f}")
```

---

### `HAP_MoE`
训练HAP-MoE（Hybrid Attention Pooling - Mixture of Experts）深度学习模型，用于谷值特征的多分类任务。该模型集成了注意力机制、多专家网络、自适应损失函数，并采用5折交叉验证集成。

#### 参数:
- `json_file_path` (str, 可选): JSON数据文件路径，默认`"processed_valleys_data.json"`。
- `test_size` (float, 可选): 测试集比例，默认0.15。
- `n_splits` (int, 可选): 交叉验证折数，默认5。
- `seed` (int, 可选): 随机种子，默认42。
- `max_lr` (float, 可选): 最大学习率，默认0.002。
- `output_dir` (str, 可选): 输出目录（保存模型、图表、部署包），默认`"hap_moe_results"`。

#### 返回:
- 字典，包含：
  - `test_accuracy`: 测试集准确率。
  - `class_names`: 原始类别名称列表。
  - `simplified_names`: 简化类别名称列表。
  - `deployment_dir`: 生成的部署包路径。

#### 核心功能:
- 自动解析JSON数据（输入特征字符串、输出标签）。
- 特征工程：生成增强特征（如斜率比、面积深度比等），标准化，并使用随机森林筛选重要特征。
- 模型架构：4个专家网络、多头注意力、门控网络、残差连接、渐进式权重。
- 自适应损失：HAP_AdaptiveLoss（结合类别权重、focal loss、困难样本加权）。
- 5折交叉验证训练，每折保存最佳模型和pipeline。
- 集成预测：性能加权集成（指数权重）。
- 可视化：混淆矩阵、专家利用热图、SHAP特征重要性、选定特征相似度分析。
- 生成部署包：包含所有fold的模型、pipeline、配置文件和标签映射。

#### 使用方法:
```python
from inkhinge.core import HAP_MoE

result = HAP_MoE(
    json_file_path="processed_valleys_data.json",
    test_size=0.15,
    n_splits=5,
    seed=42,
    output_dir="my_hap_moe_run"
)
print(f"测试准确率: {result['test_accuracy']:.4f}")
print(f"部署包保存在: {result['deployment_dir']}")
```

---

### `load_HAP_MoE`
加载预训练的HAP-MoE部署包，对新数据进行两阶段预测（分类+异常检测），识别“未知”类别样本，并生成详细报告与可视化。

#### 参数:
- `deployment_dir` (str, 可选): 部署包目录路径，默认`"hap_moe_deployment_package"`。
- `new_data_path` (str, 可选): 新数据JSON文件路径，默认`"processed_valleys_data_val.json"`。
- `anomaly_threshold` (float, 可选): 异常检测阈值（0~1），越高越严格，默认0.8。
- `output_dir` (str, 可选): 输出目录（保存结果文件），默认当前目录。
- `save_plots` (bool, 可选): 是否保存可视化图像，默认`True`。
- `return_results` (bool, 可选): 是否返回结果字典，默认`True`。

#### 返回:
- 字典，包含：
  - `predictions`: 预测类别数组（-1表示“未知”）。
  - `probabilities`: 类别概率矩阵。
  - `confidence_scores`: 最大概率（置信度）。
  - `top_k_classes`: 每个样本的Top-3类别名称列表。
  - `top_k_confidences`: Top-3置信度数组。
  - `anomaly_scores`: 异常分数数组。
  - `report`: 详细报告字典（含分类指标、分布统计等）。
  - `output_files`: 生成的文件路径（JSON结果、图像）。

#### 核心功能:
- 自动加载部署包中的模型、pipeline、配置和标签映射。
- 解析新数据JSON中的特征字符串。
- 两阶段预测：
  - 第一阶段：常规集成分类，得到概率和置信度。
  - 第二阶段：基于置信度、概率熵、特征距离计算异常分数，标记低置信度/高异常样本为“unknown”。
- 生成详细报告：包含类别分布、置信度分布、异常分数分布、不确定样本示例、分类报告（含unknown类别）。
- 可视化：预测类别分布、置信度直方图、异常分数直方图、确定vs不确定饼图。
- 保存结果JSON和图像。

#### 使用方法:
```python
from inkhinge.core import load_HAP_MoE

results = load_HAP_MoE(
    deployment_dir="hap_moe_results/hap_moe_deployment_package",
    new_data_path="new_valley_data.json",
    anomaly_threshold=0.8,
    output_dir="prediction_output",
    save_plots=True
)
print(f"预测完成，不确定样本比例: {results['report']['summary']['uncertain_ratio']:.2%}")
print(f"结果JSON保存至: {results['output_files']['results_json']}")
```

---

### `GrayValueCalculation`类
提供图像灰度值精准计算功能，支持单张/批量图片处理，可通过RGB范围筛选特定区域（如目标物体、背景排除），适用于图像光谱特征与像素级分析。

#### 静态方法`process_single_image`
处理单张图片，筛选符合RGB范围的区域，计算有效区域的平均灰度值并输出结果文件。

##### 参数:
- `image_path` (str): 图片文件路径。
- `red_range` (tuple): 红色通道范围，格式`(最小值, 最大值)`（0-255）。
- `green_range` (tuple): 绿色通道范围，格式`(最小值, 最大值)`（0-255）。
- `blue_range` (tuple): 蓝色通道范围，格式`(最小值, 最大值)`（0-255）。
- `max_valid_width` (int): 有效区域的最大宽度（像素）。
- `max_valid_height` (int): 有效区域的最大高度（像素）。
- `region_size` (int): 基础分析区域大小（如9表示9×9像素块）。
- `output_dir` (str, 可选): 结果文件保存目录，默认`"results"`。

##### 返回:
- 字典：包含`image_path`（图片路径）、`overall_average`（所有有效区域的平均灰度值）、`result_file`（结果文件路径）；处理失败返回`None`。


#### 静态方法`process_images`
批量处理图片（自动识别文件/目录），生成每张图片的灰度值结果与汇总报告。

##### 参数:
- `input_path` (str): 单个图片文件路径或包含图片的目录路径。
- `red_range` (tuple)、`green_range` (tuple)、`blue_range` (tuple): 同`process_single_image`。
- `max_valid_width` (int)、`max_valid_height` (int)、`region_size` (int): 同`process_single_image`。
- `output_dir` (str, 可选): 结果文件保存目录，默认`"results"`。

##### 返回:
- 列表：包含每张图片的处理结果字典；输入路径无效或处理失败返回空列表。

##### 支持图片格式:
`.png`, `.jpg`, `.jpeg`, `.tif`, `.tiff`

#### 使用方法:
```python
from inkhinge.core import GrayValueCalculation

# 处理单张TIF图片
single_result = GrayValueCalculation.process_single_image(
    image_path="tifdemo/an.tif",
    red_range=(0, 15),
    green_range=(0, 15),
    blue_range=(0, 15),
    max_valid_width=10,
    max_valid_height=10,
    region_size=9,
    output_dir="analysis_results"
)
print(f"单张图片平均灰度值：{single_result['overall_average']:.2f}")

# 批量处理目录中的所有图片
batch_results = GrayValueCalculation.process_images(
    input_path="image_directory/",
    red_range=(0, 15),
    green_range=(0, 15),
    blue_range=(0, 15),
    max_valid_width=10,
    max_valid_height=10,
    region_size=9,
    output_dir="batch_analysis_results"
)
print(f"批量处理完成，成功处理{len(batch_results)}张图片")
```

---

### `TifToPng`类
轻量型TIF到PNG格式转换工具，支持单文件精准转换与目录批量转换，自动处理文件命名与目录创建，确保图像兼容性。

#### 静态方法`convert_single`
将单个TIF文件转换为PNG格式，支持自定义输出路径。

##### 参数:
- `input_path` (str): TIF文件路径。
- `output_path` (str, 可选): 输出PNG文件路径，默认在原目录生成同名PNG。

##### 返回:
- 布尔值：`True`表示转换成功，`False`表示失败。


#### 静态方法`batch`
批量转换目录中所有TIF文件为PNG格式，支持自定义输出目录。

##### 参数:
- `input_dir` (str): 包含TIF文件的目录路径。
- `output_dir` (str, 可选): 输出PNG文件的目录路径，默认使用输入目录。

#### 使用方法:
```python
from inkhinge.core import TifToPng

# 单文件转换（默认输出到原目录）
TifToPng.convert_single("input.tif")

# 单文件转换（指定输出路径）
TifToPng.convert_single("tifdemo/an.tif", "tifdemo/an.png")

# 批量转换（默认输出到输入目录）
TifToPng.batch("input_dir")

# 批量转换（指定输出目录）
TifToPng.batch("input_dir", "output_dir")
```

---

### `insert_crystals`
将晶体结构（分子、离子或原子）插入主体结构，考虑周期性边界条件与原子碰撞规避，适用于材料模拟与晶体工程场景。

#### 参数:
- `host_path` (str): 主体结构文件路径（如CIF格式）。
- `insert_path` (str): 待插入结构文件路径（如CIF格式）。
- `center` (tuple): 插入区域中心坐标 `(x, y, z)`（单位与主体结构一致）。
- `radius` (float): 插入区域半径（控制插入范围）。
- `num` (int): 待插入的结构数量。
- `tolerance` (float, 可选): 碰撞容忍度（0.0-1.0，值越小碰撞限制越严格），默认0.9。
- `max_attempts` (int, 可选): 最大插入尝试次数（避免无限循环），默认1000。
- `output_path` (str, 可选): 输出结构文件路径，默认`None`（不保存）。
- `view_crystals` (bool, 可选): 是否可视化插入后的结构，默认`True`。

#### 返回:
- ASE的Atoms对象：插入后的完整晶体结构。

#### 核心功能:
- 自动识别插入结构类型（分子、离子、原子），采用对应插入策略。
- 基于周期性边界条件计算原子间最小距离，避免插入结构与主体结构过度重叠。
- 支持自定义原子半径字典，适配不同元素的碰撞判断需求。
- 在指定球形区域内随机生成插入位置，确保插入范围可控。

#### 使用方法:
```python
from inkhinge.core import insert_crystals

# 插入5个NaCl结构到MIL-101主体中
insert_crystals(
    host_path="6_mil-101_pbesol-ot_optcell.cif",
    insert_path="NaCl_insert.cif",
    center=[10.0, 10.0, 10.0],
    radius=5.0,
    num=5,
    tolerance=0.9,
    max_attempts=1000,
    output_path="result.cif"
)
```

---

## 功能特点
1. **多类型数据兼容**：  
   - 覆盖光谱（SPA）、生物信号（ABF）、图像（TIF/PNG/JPG）、晶体结构（CIF）四大类科研数据。
   - 适配ABF2及以下版本、Omnic SPA全版本，支持100000 Hz高采样率生物信号处理。

2. **高精度与鲁棒性**：  
   - 光谱转换保留20位小数精度，避免科学计数法损失数据；ABF转换自动处理通道长度不匹配（截断/补NaN）。
   - 拟合过程加入物理约束（如振幅非负、峰位在波数范围内），失败时启用备用初始值，提升复杂数据拟合成功率。
   - 所有文件操作均包含路径校验与目录自动创建，避免“目录不存在”“路径为文件”等常见错误。

3. **自动化与便捷性**：  
   - 单函数支持“文件/目录”双输入（如`abf_to_csv`自动切换单文件/批量模式），减少函数调用复杂度。
   - 批量处理支持递归子目录，合并数据结构适配深度学习输入格式（如光谱CSV列对应时间点）。
   - 图像分析与格式转换无需手动筛选文件，自动识别支持格式并生成结果报告。

4. **可视化与可解释性**：  
   - 曲线拟合自动生成“原始数据散点+拟合曲线”图，三维拟合输出曲面对比图，支持实时预览。
   - 拟合结果包含参数、R²值、表达式，晶体插入支持可视化验证，所有结果可导出为文本文件追溯。
   - 峰检测提供全局检测图、连接峰事件图、原始/滤波对比细节图，便于人工核查。
   - 机器学习模型输出混淆矩阵、专家利用热图、SHAP特征重要性、特征相似度矩阵，增强模型透明度。
   - 两阶段预测提供置信度分布、异常分数分布、不确定样本示例，辅助决策。

5. **深度学习集成**：  
   - 内置HAP-MoE先进分类模型，支持多分类、不平衡数据、困难样本挖掘。
   - 自动生成部署包，便于模型迁移与二次开发。
   - 两阶段预测有效识别未知类别，提升实际应用可靠性。


## 贡献
若您希望为`inkhinge`工具集贡献功能或修复问题，请遵循以下步骤：
1. Fork本项目仓库
2. 创建特性分支（如`git checkout -b feature/ABFv3Support`）
3. 提交代码更改（如`git commit -m 'Add ABF3 format support'`）
4. 推送分支至远程仓库（如`git push origin feature/ABFv3Support`）
5. 打开Pull Request并描述功能细节


## 许可证
本项目采用**MIT许可证**，允许自由使用、修改与二次分发，详情请见[LICENSE](LICENSE)文件。
