# acadtools

**Repository Path**: jcstone/acadtools

## Basic Information

- **Project Name**: acadtools
- **Description**: AutoCAD 外部工具箱
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-30
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# acadtools —— AutoCAD 外部工具箱

![Python](https://img.shields.io/badge/Python-3.11+-blue)
![PySide6](https://img.shields.io/badge/PySide6-6.11.1-green)
![License](https://img.shields.io/badge/License-AGPL--3.0-red)
![Platform](https://img.shields.io/badge/Platform-Windows-lightgrey)
![Version](https://img.shields.io/badge/Version-v26.8.1-orange)

> 一个运行于 AutoCAD 之外（外部进程）的辅助工具箱，通过 **COM（ActiveX Automation）** 与正在运行的 **AutoCAD 2022+** 通信，把重复性高、手工程度高的制图任务封装成可双击执行的功能项。

> **版本号**：程序版本号统一由全局常量 `acadtools.__version__` 定义（见 `acadtools/__init__.py`），about 信息与程序界面均从此处读取；升级版本只需修改该处一处。

**Author: jcstone ｜ Email: 64071284@qq.com ｜ Gitee: [https://gitee.com/jcstone/acadtools](https://gitee.com/jcstone/acadtools)**

[English README](README.en.md) ｜ [总设计方案](docs/DESIGN.md) ｜ [操作手册](docs/MANUAL.md) ｜ [扩展开发](docs/EXTEND.md) ｜ [示例集](docs/EXAMPLES.md)

---

## 目录

- [项目简介](#项目简介)
- [特性](#特性)
- [功能清单](#功能清单)
- [软件架构](#软件架构)
- [安装教程](#安装教程)
- [使用说明](#使用说明)
- [常见问题](#常见问题)
- [参与贡献](#参与贡献)
- [许可证](#许可证)

---

## 项目简介

`acadtools` 是一个**运行于 AutoCAD 之外**的辅助工具箱。它以「总在最前、无边框、停靠屏幕左侧」的常驻面板形式运行，通过 COM 与正在运行的 AutoCAD 实例通信，将图纸管理、图层管理、数据采集、格式统一、辅助编辑、辅助绘图、图块管理等高频重复的制图任务，统一封装为可**双击即执行**的功能项。

设计目标：

- **外部常驻**：不随某个 AutoCAD 文档生命周期绑定，独立窗口常驻屏幕，随用随点。
- **零部署成本**：单机 Python 脚本 + PySide6，无服务端、无数据库、无网络依赖。
- **即插即用的扩展**：新增一个功能 = 新增一个被 `@tool` 装饰的类，主窗口自动在树中显示，无需改动框架。
- **图层级文件系统数据层**：图块管理基于 `blocks/<组>/<图块>.dwg` 目录，无需 JSON/数据库，便于手工维护。

## 特性

- **无边框置顶常驻窗口**：自定义标题栏、四边/四角拖拽缩放、默认停靠屏幕左侧垂直居中，并适配多显示器插拔。
- **AutoCAD 连接状态指示**：状态栏彩色圆点实时显示连接状态，点击可重新检测；交互拾点/绘图时自动管理窗口焦点（`acad_interaction()`），结束后恢复置顶。
- **7 大类、24 项功能**：图纸管理、图层管理、数据采集（CSV）、格式管理、辅助编辑、辅助绘图（WKT/CSV）、图块管理。
- **图块资源管理**：基于 `blocks/<组>/<图块>.dwg` 文件系统，支持新增当前图纸到组、插入到当前图纸、回归原点、复制到新图纸等。
- **暗黑主题**：统一深色调色板，原生对话框与主窗口风格一致。
- **统一的执行计时与结果反馈**：每个工具自动记录开始/结束时间与总用时，失败语义清晰。

## 功能清单

| 分类 | 功能 |
|---|---|
| **图纸管理** | 当前图纸信息、一键创建新图纸、一键关闭所有图纸文件、图纸清理、DWG 批量转换为 DXF |
| **图层管理** | 更改所选实体图层、所有实体按图例颜色分层 |
| **数据采集** | 采集所选点到 CSV、采集所选点和点标注文字到 CSV、采集所选圆到 CSV、采集所选图块到 CSV、采集所选直线到 CSV、采集所选多段线到 CSV、采集所选线对象到 CSV、采集所选文字到 CSV |
| **格式管理** | 一键设置中文字体、批量设置中文字体 |
| **辅助编辑** | 左对齐所选文字、水平对齐所选文字、所选文字平均行间距、所选文字平均列间距 |
| **辅助绘图** | 标绘 CSV 点坐标、依 CSV(WKT) 绘制实体、依 WKT 绘制图形实体 |
| **图块管理** | 图块库管理（基于 `blocks/` 目录，见「使用说明」） |

> 「我的工具」分类为预留的自定义分类，内置开发模板，用户可在此扩展私有功能。

## 软件架构

```
┌───────────────────────────── 外部进程 (python) ─────────────────────────────┐
│  main.py ─▶ acadtools.__init__ ─▶ toolbox.py: ToolboxWindow (主窗口)        │
│                │                    ├─ TitleBar（无边框标题栏）              │
│                │                    ├─ QTabWidget                            │
│                │                    │    ├─ 工具箱页（QTreeWidget）          │
│                │                    │    └─ 图块管理页（BlockManagement）    │
│                │                    ├─ StatusIndicator（连接指示器）         │
│                │                    └─ closeEvent（防悬空引用）              │
│                ├─ core/                                                      │
│                │    ├─ registry.py    @tool 装饰器 + 注册表                 │
│                │    ├─ base.py        Tool 基类（run/execute/timing/failed） │
│                │    ├─ acad.py        AutoCAD 连接与图层操作封装             │
│                │    └─ window_focus.py acad_interaction() 焦点管理上下文     │
│                ├─ resources/                                                 │
│                │    ├─ library.py     blocks/ 目录数据层（纯文件系统）        │
│                │    └─ panel.py       BlockManagementPanel（图块管理 UI）    │
│                └─ tools/                                                     │
│                     ├─ drawing_management / layer_management                 │
│                     ├─ data_collection / format_management                   │
│                     ├─ assist_edit / aux_draw / custom                       │
│                     └─ 每个 tool_*.py：被 @tool 装饰的 Tool 子类              │
│            ────── AutoCAD COM (ActiveX Automation) ──────                    │
│            AutoCAD 2022+ ── Application / Documents / ModelSpace /           │
│            Utility.GetPoint / SendCommand / PickfirstSelectionSet            │
└──────────────────────────────────────────────────────────────────────────────┘
```

### 技术栈与依赖

| 依赖 | 版本 | 用途 |
|---|---|---|
| Python | 3.11+ | 运行时 |
| PySide6 | 6.11.1 | Qt GUI（无边框窗口、树、样式表） |
| AutoCAD（库） | 0.1.12 | AutoCAD COM 封装（顶层模块 `AutoCAD` / `APoint`，win32com 后端，非 pyautocad） |
| pywin32 | ≥312 | `win32gui` / `win32con` / `win32com.client` 窗口与焦点控制 |
| psutil | ≥5.9 | AutoCAD 库的运行时依赖（进程/系统查询） |
| AutoCAD | 2022+ | 本机安装并运行 |

### 核心设计要点

- **功能注册表**：`@tool(category, name, description)` 装饰器在导入时自动登记工具；主窗口读取注册表构建树形控件。
- **Tool 基类模板方法**：`execute()` 统一计时，再调 `run()`；`failed` 标志区分「执行完成」与「执行结束」。
- **焦点管理**：`acad_interaction()` 上下文管理器统一处理交互拾点/命令时工具箱的置顶切换，保证 AutoCAD 可获前台焦点，交互后自动恢复。
- **图块文件系统数据层**：`blocks/<组>/<图块>.dwg`，纯文件系统、可手工维护、可版本管理。

## 安装教程

### 环境要求

- Windows 操作系统
- 已安装并正在运行 **AutoCAD 2022+**
- 已安装 **Python 3.11+**（并已加入系统 `PATH`，或使用官方 Python / Anaconda 安装器自带的 `py` 启动器）

### 第 1 步：创建环境变量（PATH 等）

本项目通过 COM 与 AutoCAD 通信、用 PySide6 构建 GUI，运行环境依赖以下环境变量：

| 环境变量 | 作用 | 说明 |
|---|---|---|
| `PATH` | 定位 Python 解释器与可执行文件 | 需包含 Python 安装目录；若使用虚拟环境，则指向 `venv\Scripts`（见第 3 步） |

> 说明：项目代码本身不读取自定义配置环境变量，日志固定写入 `%USERPROFILE%\acadtools.log`。下面步骤以 Windows 上设置 `PATH` 为例。

**方式一（临时，当前终端生效）：**

```powershell
# 假设 Python 安装在 C:\Python312
set PATH=C:\Python312;C:\Python312\Scripts;%PATH%
```

**方式二（永久，写入用户环境变量）：**

```powershell
# 将 Python 目录加入当前用户 PATH（永久生效）
[Environment]::SetEnvironmentVariable("Path",
  "C:\Python312;C:\Python312\Scripts;" +
  [Environment]::GetEnvironmentVariable("Path", "User"),
  "User")
```

修改后**重新打开终端**使环境变量生效，并验证：

```powershell
python --version
```

### 第 2 步：克隆 / 下载项目

```bash
git clone https://gitee.com/jcstone/acadtools.git
cd acadtools
```

### 第 3 步：创建并激活虚拟环境（推荐）

在项目根目录创建独立虚拟环境，避免污染全局 Python：

```powershell
# 在项目根目录创建虚拟环境 .venv
python -m venv .venv

# 激活虚拟环境（PowerShell）
.\.venv\Scripts\Activate.ps1
# 激活虚拟环境（CMD）
# .venv\Scripts\activate.bat
```

> 若 PowerShell 提示「禁止运行脚本」，请先放开执行策略（以管理员运行）：
> `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`
>
> 激活后终端提示符前会出现 `(.venv)`，此时 `PATH` 已自动指向 `.venv\Scripts`。

### 第 4 步：安装 Python 依赖

激活虚拟环境后，安装 `requirements.txt` 中的依赖：

```bash
pip install -r requirements.txt
```

> - 依赖清单见 [技术栈与依赖](#技术栈与依赖)。
> - `AutoCAD` 库与 `pywin32` 会自动处理其传递依赖（如 `psutil`）。
> - 国内网络可追加镜像源加速：`pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple`

### 第 5 步：（可选）准备图块库目录

按需创建 `blocks/<组>/<图块名>.dwg`，目录结构即图块分组。

### 启动

```bash
python main.py
```

工具箱启动后自动停靠在屏幕**左侧垂直居中**，无边框、总在最前。

> 提示：若不在虚拟环境中直接使用全局 Python，请确保已按「第 1 步」配置好 `PATH`，再执行 `python main.py`。

## 使用说明

### 界面构成

```
┌─────────────────────────────┐
│ [图标] ACAD工具箱      [—][×] │  ← 标题栏（可拖动）
├─────────────────────────────┤
│  工具箱 │ 图块管理           │  ← Tab 页
│  ▼ 图纸管理                  │  ← 分类（手风琴）
│    当前图纸信息              │
│    ...                      │
│  ▼ 图层管理 / 数据采集 / ... │
│  ─────────────────────────  │
│  描述面板（说明/运行结果）    │
│ ● AutoCAD (2024) 就绪        │  ← 状态栏
└─────────────────────────────┘
```

- **单击**分类节点：展开/收起（手风琴，同时折叠其它分类）。
- **单击**功能项：显示该功能说明（不执行）。
- **双击**功能项：立即执行。
- **描述面板**：显示功能说明、运行进度、执行结果（含开始/结束时间、总用时）。
- **状态栏圆点**：🟢 绿色=已连接；🔴 红色=未连接；🟡 黄色=检测中。点击可重新检测。

### 图块管理

切到 **「图块管理」** Tab 管理 `blocks/` 目录下的图块：

| 操作 | 说明 |
|---|---|
| **新增当前图纸到组** | 把当前 AutoCAD 图纸另存为 `blocks/<组>/<块名>.dwg` |
| **插入到当前图纸** | 拾取插入点后把该图块插入当前图纸（可设固定比例/旋转角度） |
| **复制所选图形到新图纸** | 把当前选择集复制粘贴到新建图纸 |
| **当前选择图块回归原点** | 把选中图块插入点归到 (0,0,0)、旋转角归零 |
| **删除 / 重命名** | 删除或重命名分组 / 图块 |

> 修改图块库：直接编辑 `blocks/<组>/` 下的 `.dwg` 文件即可，重启工具箱自动刷新。

### 日志

- 异常日志：`%USERPROFILE%\acadtools.log`

## 打包

```bash
py -m PyInstaller acadtools.spec --noconfirm --clean


```


## 常见问题

| 问题 | 解决方法 |
|---|---|
| 双击功能无反应 / 状态栏红点 | 确认 AutoCAD 已安装并运行，点击状态栏重新检测连接 |
| 报「AutoCAD 未连接」但已打开 | 以管理员身份运行，或重启 AutoCAD 后点击状态栏重试 |
| 交互拾点后工具箱窗口消失 | 升级到 v26.8.1 以上（焦点管理 bug 已修复） |
| 插入图块输入旋转角度后命令行卡住 | 升级到最新版；输入角度后按一次 Enter 即可 |

## 参与贡献

欢迎 Fork 本仓库并提交 Pull Request：

1. **Fork** 本仓库
2. 新建功能分支：`git checkout -b Feat_xxx`
3. 新增工具功能（详见 [扩展开发文档](docs/EXTEND.md)）
4. 提交代码：`git commit -m "feat: xxx"`
5. 推送分支：`git push origin Feat_xxx`
6. 新建 Pull Request


> 提交前请确保通过单元测试：`python -m unittest discover -s tests -p 'test_*.py'`

## 许可证

本项目基于 **GNU Affero General Public License v3.0**（AGPL-3.0）开源，详见 [LICENSE](LICENSE)。

---

Copyright © 2026 **jcstone**. 本项目仅供学习与交流，如有问题或者进一步扩展开发，欢迎通过 Email（64071284@qq.com）或 Gitee Issues 反馈。