Two D Classifier

二维材料分类器🧬

一个干净、现代的深度学习框架，用于2D材料分类，从CC_v12项目中提取和重构。支持各种2D材料的分类，包括石墨烯、hBN（六方氮化硼）和其他分层材料。

🚀 快速开始

安装

# Clone or download this project
cd twoDClassifier

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

基本用法

from src.model_loader import load_graphene_model

# Load a pretrained model (supports various 2D materials)
classifier = load_graphene_model('hBN_monolayer')  # or 'graphene_1', 'hBN', etc.

# Make prediction on an image
prediction = classifier.predict_single_image('path/to/image.jpg')
print(f"Prediction: {'Good' if prediction == 1 else 'Bad'}")

# Get probabilities
probs = classifier.predict_single_image('path/to/image.jpg', return_probabilities=True)
print(f"Good probability: {probs[0][1]:.3f}")

运行示例

# Command line example
python examples/basic_usage.py

# GUI Application
python examples/gui_app.py

📁 项目结构

twoDClassifier/
├── models/                 # Pretrained models for various 2D materials
│   ├── graphene_1/
│   │   ├── trained_model.json
│   │   └── trained_model.h5
│   ├── graphene_2/
│   │   ├── trained_model.json
│   │   └── trained_model.h5
│   ├── hBN/
│   │   ├── trained_model.json
│   │   └── trained_model.h5
│   ├── hBN_monolayer/
│   │   ├── trained_model.json
│   │   └── trained_model.h5
│   └── [other 2D material models...]
├── src/                   # Source code
│   ├── __init__.py
│   ├── model_loader.py    # Model loading utilities
│   └── image_utils.py     # Image preprocessing
├── examples/              # Usage examples and demos
│   ├── basic_usage.py     # Command-line usage example
│   ├── gui_app.py         # GUI testing application
│   ├── test_mcp_simple.py # MCP server testing
│   └── mcp_client_example.py  # MCP client example
├── data/                  # Sample test images (uploaded images stored here)
├── GUI_USAGE.md           # GUI usage guide
├── mcp_http_server.py     # HTTP/REST MCP server for web clients
├── mcp_fastmcp_server.py  # FastMCP server (HTTP + stdio transport, 88 lines)
├── mcp_fastmcp_stdio_server.py  # FastMCP stdio-only server (Claude Desktop)
├── start_server.py        # Unified server launcher with port fallback
├── start_http_server.py   # HTTP server launcher with port fallback
├── start_fastmcp_server.py # FastMCP HTTP server launcher with port fallback
├── claude_desktop_config.json  # Claude Desktop configuration example
├── MCP_USAGE.md           # HTTP MCP server documentation
├── todo.md                # Development planning document
├── requirements.txt
└── README.md

🧠 模型架构

所有预训练模型都使用针对2D材料分类优化的CNN架构：

标准架构（跨材料类型使用）：

• 输入：RGB图像（大小灵活，默认100x100）
• 4个具有最大池化的卷积层
• 过滤器：32→ 64 → 128 → 256
• 全局最大池化+退出
• 二进制分类输出

主要特点：

• 自动图像预处理（中心裁剪+调整大小）
• 类平衡支持
• TensorFlow 2.x兼容
• 简洁、模块化的代码结构
• GUI测试界面 便于模型/图像测试
• 多型号支持 （9种预训练型号可供选择）
• 样本数据和示例 用于即时测试

📊 模型性能

这些模型在2D材料显微镜图像上进行训练，以对不同材料（石墨烯、hBN等）的薄片质量进行分类：

• 类别0：劣质/劣质薄片
• 1级：优质/高质量薄片

🖥️ GUI应用程序

为了便于测试和演示，请使用附带的GUI：

python gui_app.py

GUI功能：

• 图像选择：上传您自己的图像或使用现有的图像 data/ 文件夹
• 模型选择：从9种可用型号中选择（石墨烯、hBN变体）
• 实时预测：即时结果和信心评分
• 视觉界面：图像预览和颜色编码结果
• 模型比较：在不同型号之间轻松切换

看 GUI_USAGE.md 详细说明。

🌐 MCP服务器（远程访问和克劳德桌面）

该项目包括 双MCP服务器支持 为了获得最大的兼容性：

服务器选项

1.HTTP/REST服务器(mcp_http_server.py) -对于web客户端和API访问：

# Install HTTP server dependencies
pip install fastapi 'uvicorn[standard]' python-multipart httpx

# Start HTTP server (default: localhost:8000)
python mcp_http_server.py

# Custom IP and port for remote access
python mcp_http_server.py --host 0.0.0.0 --port 8001

2.FastMCP服务器(mcp_fastmcp_server.py) -对于MCP客户(⭐ 代码减少70%):

# Install FastMCP dependencies
pip install fastmcp tensorflow opencv-python pillow numpy

# Start HTTP server (default: localhost:8000 with port fallback)
python mcp_fastmcp_server.py

# Custom configuration
python mcp_fastmcp_server.py --host 0.0.0.0 --port 8001

# For stdio transport (Claude Desktop)
python mcp_fastmcp_server.py --transport stdio
# OR use dedicated stdio server
python mcp_fastmcp_stdio_server.py

为什么是两台服务器？

• HTTP服务器：非常适合web应用程序、远程API访问、生产部署
• FastMCP服务器：与MCP客户端无缝集成，代码简洁明了
• 两者共享相同的模型逻辑：无重复，结果一致

可用的MCP工具（两台服务器）

• upload_image -上传图像进行分类（最多支持16MB文件）
• list_models -获取可用型号列表（9款）
• predict_flake_quality -使用置信度分数进行质量预测
• get_prediction_history -访问预测历史

使用示例

HTTP客户端（Web/API）:

import requests, base64

server = "http://localhost:8000"  # or remote IP

# Upload and analyze
with open("image.jpg", "rb") as f:
    data = {"image_data": base64.b64encode(f.read()).decode(), "filename": "image.jpg"}
upload = requests.post(f"{server}/mcp/tools/upload_image", data=data)

prediction = requests.post(f"{server}/mcp/tools/predict_flake_quality", 
    data={"model_name": "hBN_monolayer", "image_filename": upload.json()["filename"]})
print(f"Quality: {prediction.json()['quality']}")

MCP客户端集成:

*HTTP客户端（web/API）*:

import requests
response = requests.get("http://localhost:8000/mcp/tools/list_models")

*克劳德桌面（stdio）*:

1. 使用完整路径配置客户端 mcp_fastmcp_stdio_server.py
2. 与AI聊天： *“有哪些二维材质模型可用？”*
3. 上传图片： *“你能分析一下这种石墨烯薄片的质量吗？”*

代码比较

文档:

• MCP_USAGE.md -HTTP服务器API参考

🛠️ 高级用法

自定义预处理

from src.image_utils import CenterCrop
from PIL import Image
import numpy as np

# Load and preprocess image manually
image = Image.open('image.jpg')
transform = CenterCrop(crop_size=float('inf'), target_size=100)
processed_image = transform(image)
image_array = np.array(processed_image)

# Make prediction
prediction = classifier.predict(image_array)

批量预测

# Process multiple images at once
image_batch = np.stack([image1, image2, image3])  # Shape: (3, height, width, 3)
predictions = classifier.predict(image_batch)

模型信息

# Get detailed model information
info = classifier.get_model_info()
print(f"Input shape: {info['input_shape']}")
print(f"Trainable parameters: {info['trainable_params']}")

📋 需求

• Python 3.8-3.10
• TensorFlow 2.8+
• OpenCV
• 枕头
• 数值Python
• Tkinter（包含在Python中-用于GUI）

🎯 用例

该框架非常适合：

• 研究二维材料质量评估（石墨烯、hBN、过渡金属二硫化物等）
• 工业的：材料制造中的自动化质量控制
• 教育的：深度学习演示和材料科学教学
• 发展：材料分类系统的快速原型制作
• 分析：显微镜图像的批处理

🔧 故障排除

常见问题

1. 模型加载错误：确保两者 .json 和 .h5 文件存在
2. 图像大小问题：模型自动处理不同的输入大小
3. 内存错误：小批量处理图像
4. TensorFlow警告：这些通常可以忽略

性能提示

• 对多幅图像使用批处理
• 考虑图像大小与精度之间的权衡
• 如果CUDA可用，GPU加速会自动工作

🚀 当前状态和下一阶段

第1阶段-已完成：

• ✅ 多材料二维分类框架（石墨烯、hBN等）
• ✅ 干净的模块化代码库，包含9个预训练模型
• ✅ 命令行界面和综合示例
• ✅ GUI应用程序，便于测试和演示
• ✅ 样本数据和完整文件

第2阶段-已完成：

• ✅ 双MCP服务器架构 支持web和MCP客户端
• ✅ HTTP/REST服务器 （288行）用于web应用程序和远程API访问
• ✅ FastMCP服务器 （88行）支持HTTP+stdio传输
• ✅ 统一服务器启动器 具有自动端口回退功能
• ✅ 共享模型逻辑 -两台服务器使用相同的分类算法
• ✅ 网络可访问服务 具有可配置的IP/端口绑定
• ✅ 生产就绪架构 有全面的文件

第3阶段-已完成：

• ✅ 项目组织 -将示例移动到 examples/ 目录
• ✅ 代码清理 -删除了过时的配置和测试文件
• ✅ 文档更新 -反映当前项目结构
• ✅ 服务器启动器脚本 -多种选项，便于部署

为第4+阶段做好准备： 高级身份验证、自定义模型培训、生产扩展和企业部署功能。

🤝 贡献

此项目是从原始CC_v12代码库中提取和清理的。在创建更可维护的结构的同时，保留了神经网络架构和预处理方法。

📄 许可证

从CC_v12项目中提取-检查原始项目的许可信息。

📚 参考文献

• 显微镜自动化原始CC_v12项目
• TensorFlow/Keras文档
• 二维材料表征的材料科学研究