KeyForge3D
KeyForge3D is an innovative application that extracts the shape of a physical key from a photo, generates a 3D model of the key, and exports it as an STL file for 3D printing. This tool is designed for locksmiths, hobbyists, or anyone needing a quick way to replicate a key using a 3D printer. The app features a user-friendly GUI built with Tkinter, making it easy to upload an image, process the key, and generate a 3D model.
KeyForge3D 是一个创新的应用程序，它可以从照片中提取物理钥匙的形状，生成钥匙的 3D 模型，并将其导出为 STL 文件进行 3D 打印。该工具专为锁匠、业余爱好者或任何需要使用 3D 打印机快速复制钥匙的人而设计。该应用程序具有使用 Tkinter 构建的用户友好型 GUI，可以轻松上传图像、处理密钥和生成 3D 模型。
Features 特征
- Key Shape Extraction: Upload a photo of a key to extract its 2D profile.
Key Shape Extraction ：上传键的照片以提取其 2D 配置文件。 - Bitting Analysis: Automatically detect and analyze the key’s bitting pattern (e.g., "05624").
咬合分析 ：自动检测和分析键的咬合模式（例如，“05624”）。 - 3D Model Generation: Convert the 2D key profile into a 3D model with accurate cuts and dimensions.
3D 模型生成 ：将 2D 键轮廓转换为具有精确切割和尺寸的 3D 模型。 - STL Export: Export the 3D model as an STL file, ready for 3D printing.
STL 导出 ：将 3D 模型导出为 STL 文件，以便进行 3D 打印。 - User-Friendly GUI: Simple interface to upload images and generate models with a single click.
用户友好的 GUI ：简单的界面，只需单击一下即可上传图像和生成模型。 - Scalability: Scale the key to real-world dimensions (default: 1 pixel = 0.1 mm; can be adjusted with a reference object).
可扩展性 ：将抠像缩放到实际尺寸（默认值：1 像素 = 0.1 毫米;可以使用参考对象进行调整）。
Demo 演示
The app processes a photo of a key, extracts its shape, and generates a 3D model like the one shown above. The bitting code (e.g., "05624") is also displayed for reference.
该应用程序处理钥匙的照片，提取其形状，并生成如上所示的 3D 模型。还会显示咬合代码（例如，“05624”）以供参考。
Installation 安装
Prerequisites 先决条件
- Python 3.8+: Ensure Python is installed on your system.
Python 3.8+ ：确保您的系统上已安装 Python。 - pip: Python package manager for installing dependencies.
pip ：用于安装依赖项的 Python 包管理器。 - 3D Printer (Optional): To print the generated key models.
3D 打印机（可选）： 打印生成的关键模型。
Dependencies 依赖
KeyForge3D relies on the following Python libraries:
KeyForge3D 依赖于以下 Python 库：
opencv-python: For image processing and key shape extraction.
opencv-python：用于图像处理和关键形状提取。numpy: For numerical operations.
numpy：用于数值运算。trimesh: For 3D model generation and STL export.
trimesh：用于 3D 模型生成和 STL 导出。shapely: For polygon operations.
shapely：用于多边形作。pillow: For image display in the GUI.
pillow：用于在 GUI 中显示图像。
Install the dependencies using the following command:
使用以下命令安装依赖项：
pip install opencv-python numpy trimesh shapely pillow
Clone the Repository 克隆存储库
Clone the KeyForge3D repository to your local machine:
将 KeyForge3D 存储库克隆到本地计算机：
git clone https://github.com/makalin/KeyForge3D.git
cd KeyForge3D
Usage 用法
- Run the App:运行应用程序 ：
- Run the main script to launch the GUI:
运行主脚本以启动 GUI：
python keyforge3d.py - Run the main script to launch the GUI:
- Upload a Key Photo:
上传关键照片 ：- Click the "Upload Key Image" button and select a photo of a key.
点击 “Upload Key Image” 按钮并选择密钥的照片。 - The key should be placed on a plain background (e.g., white paper) with good lighting for best results.
键应放置在具有良好照明的纯色背景（例如，白纸）上以获得最佳效果。 - Optionally, include a reference object (e.g., a coin) for accurate scaling (scaling is currently set to 1 pixel = 0.1 mm).
（可选）包括一个参考对象（例如，硬币）以进行精确缩放（缩放当前设置为 1 像素 = 0.1 毫米）。
- Click the "Upload Key Image" button and select a photo of a key.
- Process the Key:
处理密钥 ：- Click the "Process Key and Generate 3D Model" button.
单击 “Process Key and Generate 3D Model” 按钮。 - The app will process the image, display the bitting code, and save the 3D model as
key_model.stl.
该应用程序将处理图像，显示咬合代码，并将 3D 模型保存为key_model.stl。
- Click the "Process Key and Generate 3D Model" button.
- 3D Printing:3D 打印 ：
- Open the
key_model.stlfile in your 3D printing software (e.g., Cura, PrusaSlicer).
在 3D 打印软件（例如 Cura、PrusaSlicer）中打开key_model.stl文件。 - Print the key using a strong material like PLA or ABS. Use a high resolution (e.g., 0.1 mm layer height) for accurate bitting cuts.
使用 PLA 或 ABS 等坚固材料打印键。使用高分辨率（例如，0.1 毫米层高）进行准确的咬合切割。
- Open the
Code Overview 代码概述
The main script ( keyforge3d.py ) includes:
主脚本 （ keyforge3d.py ） 包括：
- GUI: Built with Tkinter for user interaction.
GUI： 使用 Tkinter 构建，用于用户交互。 - Image Processing: Uses OpenCV to detect the key’s outline and analyze its bitting pattern.
Image Processing ：使用 OpenCV 检测键的轮廓并分析其咬合模式。 - 3D Model Generation: Uses Trimesh to create a 3D model and export it as an STL file.
3D 模型生成 ：使用 Trimesh 创建 3D 模型并将其导出为 STL 文件。 - Error Handling: Includes basic error handling for invalid images or processing failures.
错误处理 ：包括针对无效图像或处理失败的基本错误处理。
Roadmap 路线图
- Add a 3D model preview within the app.
在应用程序中添加 3D 模型预览。 - Support for scaling using a reference object (e.g., a coin).
支持使用引用对象（例如硬币）进行缩放。 - Add key type identification (e.g., Schlage SC4, Kwikset KW1).
添加密钥类型标识（例如，Schlage SC4、Kwikset KW1）。 - Improve bitting analysis accuracy with machine learning.
通过机器学习提高咬合分析的准确性。 - Create a mobile app version with camera integration.
创建具有相机集成的移动应用程序版本。 - Add support for more key profiles and bitting standards.
添加对更多关键配置文件和 bitting 标准的支持。
Contributing 贡献
Contributions are welcome! To contribute:
欢迎贡献！要做出贡献：
- Fork the repository.复刻存储库。
- Create a new branch (
git checkout -b feature/your-feature).
创建新分支 （git checkout -b feature/your-feature）。 - Make your changes and commit them (
git commit -m "Add your feature").
进行更改并提交它们 （git commit -m "Add your feature"）。 - Push to your branch (
git push origin feature/your-feature).
推送到您的分支 （git push origin feature/your-feature）。 - Open a pull request.打开拉取请求。
Please ensure your code follows the project’s coding style and includes appropriate tests.
请确保您的代码遵循项目的编码样式并包含适当的测试。
License 许可证
This project is licensed under the MIT License. See the LICENSE file for details.
本项目根据 MIT 许可证获得许可。有关详细信息，请参阅 LICENSE 文件。
Acknowledgments 确认
- Inspired by locksmith tools for key bitting analysis.
灵感来自用于钥匙咬合分析的锁匠工具。 - Built with the help of open-source libraries like OpenCV, Trimesh, and Tkinter.
在 OpenCV、Trimesh 和 Tkinter 等开源库的帮助下构建。
Contact 联系
For questions, suggestions, or feedback, feel free to open an issue or reach out.
如有问题、建议或反馈，请随时打开问题或联系我们。