Metadata-Version: 2.4
Name: fry-qt6-3d-widget
Version: 0.1.0
Summary: A reusable PyQt6 QWidget for viewing 3D models with PyVista.
Author: Fan Renyi
Project-URL: Homepage, https://gitlab.com/fanrenyi33/fry_python_lib_d150_fry_3d_view
Project-URL: Repository, https://gitlab.com/fanrenyi33/fry_python_lib_d150_fry_3d_view
Project-URL: Issues, https://gitlab.com/fanrenyi33/fry_python_lib_d150_fry_3d_view/-/issues
Keywords: pyqt6,qt,pyvista,vtk,3d,widget,gltf,stl,obj,point-cloud
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.23
Requires-Dist: PyQt6>=6.5
Requires-Dist: pyvista>=0.43
Requires-Dist: pyvistaqt>=0.11
Requires-Dist: vtk>=9.2
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
Requires-Dist: twine>=5; extra == "dev"

# fry-qt6-3d-widget

`fry-qt6-3d-widget` 是一个可复用的 PyQt6 3D 模型显示控件。它把 PyVista / VTK 的 3D 渲染能力封装成一个独立 `QWidget`，可以直接嵌入你的 PyQt6 应用。

组件本身不封装成 `QDockWidget`。如果业务应用需要 dock，只要把 `FryCore3DViewer` 放进 `QDockWidget` 即可，见 `examples/dock_viewer.py`。

## 安装

从 PyPI 安装：

```bash
pip install fry-qt6-3d-widget
```

本仓库开发安装：

```bash
python -m pip install -e ".[dev]"
```

## 最小使用

```python
import sys

from PyQt6.QtWidgets import QApplication, QMainWindow
from fry_qt6_3d_widget import FryCore3DViewer


app = QApplication(sys.argv)

window = QMainWindow()
viewer = FryCore3DViewer()
window.setCentralWidget(viewer)

viewer.load_model("path/to/model.stl")

window.resize(1200, 800)
window.show()
sys.exit(app.exec())
```

也可以直接运行安装后的 demo：

```bash
fry-qt6-3d-viewer path/to/model.stl
```

## 支持格式

- `.glb` / `.gltf`
- `.ply`
- `.obj`
- `.stl`
- `.vtk` / `.vtp` / `.vtu`
- `.xyz` / `.pts` 文本点云

`.xyz` / `.pts` 至少包含 `X Y Z` 三列；如果包含 `R G B` 三列，会按点颜色显示。

## 常用能力

- 拖拽加载模型文件
- 视角切换：等轴、正面、背面、左面、右面、顶部、底部
- 渲染模式：表面、线框、点云、表面+边
- 坐标轴、网格、地面参考开关
- 深色/浅色背景
- Y-up 输入到 Z-up 业务坐标系转换
- 点云体素 glyph 显示
- Qt 信号：加载成功、加载失败、视角变化、渲染模式变化

更多设计细节见 [docs/CORE_CONCEPTS.md](docs/CORE_CONCEPTS.md)。

## 示例

```bash
python examples/basic_viewer.py path/to/model.stl
python examples/dock_viewer.py path/to/model.stl
python examples/load_xyz_points.py
```

## 测试

```bash
python -m pytest
```

## 构建与发布

```bash
python -m build
python -m twine check dist/*
python -m twine upload dist/*
```

第一次发布建议先用 TestPyPI：

```bash
python -m twine upload --repository testpypi dist/*
```
