image-annotation-drawer 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added - 标注选中与移动功能
+
+- **选中功能**：
+  - 点击标注即可选中（青色虚线边框 + 四个角控制点）
+  - 支持矩形和多边形标注的选中
+  - 碰撞检测（点在矩形内、射线法检测点在多边形内）
+  - 支持负宽高矩形的检测（从右下往左上画的情况）
+- **移动功能**：
+  - 拖拽选中的标注即可移动位置
+  - 实时渲染，流畅体验
+- **快捷操作**：
+  - Delete / Backspace - 删除选中的标注
+  - ESC - 取消选中
+  - 点击空白处 - 取消选中
+  - 切换绘制模式自动取消选中
+- **新增 API**：
+  - `selectAnnotation(index)` - 选中指定索引的标注
+  - `deselectAnnotation()` - 取消选中
+  - `getSelectedAnnotation()` - 获取当前选中的标注
+  - `deleteSelectedAnnotation()` - 删除选中的标注
+  - `moveSelectedAnnotation(dx, dy)` - 移动选中的标注
+
+### Improved - 文本标注易用性优化
+
+- **默认空文本**：添加文本标注时默认为空字符串，不再是"双击编辑文字"
+- **视觉优化**：
+  - 圆角背景 + 阴影效果
+  - 编辑状态青色发光边框
+  - 选中时半透明背景高亮
+  - 输入框美观样式（圆角、阴影、占位符）
+- **快捷操作**：
+  - Enter - 完成编辑
+  - ESC - 取消编辑，恢复原状
+  - Delete（文本为空时）- 删除标注
+- **智能删除**：清空文本后确认，自动删除标注
+- **自适应输入框**：输入时自动调整宽度适应内容
+- **自动选中文本**：进入编辑模式时自动选中文本，方便直接替换
+
+## [1.0.0] - 2024-03-05
+
+### Added
+- Initial release
+- Support for rectangle annotations
+- Support for polygon annotations
+- Support for text annotations
+- Zoom and pan functionality
+- Undo operation (Ctrl+Z)
+- Export annotated images
+- Keyboard shortcuts
+- TypeScript support

package/CONTRIBUTING.md

@@ -0,0 +1,147 @@
+# Contributing to Image Annotation Drawer
+
+感谢你对 Image Annotation Drawer 的兴趣！我们欢迎各种形式的贡献。
+
+## 如何贡献
+
+### 报告问题
+
+如果你发现了 bug 或有功能建议，请通过 [GitHub Issues](https://github.com/KangLinDDD/ADrawer/issues) 提交。\n
+提交问题时请包含：
+- 问题的清晰描述
+- 复现步骤
+- 期望行为 vs 实际行为
+- 浏览器环境和版本
+- 如果有截图会更好
+
+### 提交代码
+
+1. **Fork 仓库**
+   ```bash
+   # 点击 GitHub 上的 Fork 按钮
+   ```
+
+2. **克隆你的 Fork**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/ADrawer.git
+   cd ADrawer
+   ```
+
+3. **创建分支**
+   ```bash
+   git checkout -b feature/your-feature-name
+   # 或
+   git checkout -b fix/your-bug-fix
+   ```
+
+4. **安装依赖并开发**
+   ```bash
+   npm install
+   npm run dev
+   ```
+
+5. **确保代码质量**
+   ```bash
+   npm run lint
+   npm test
+   npm run build
+   ```
+
+6. **提交更改**
+   ```bash
+   git add .
+   git commit -m "feat: add some feature"
+   ```
+
+7. **推送到你的 Fork**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+8. **创建 Pull Request**
+   - 访问 https://github.com/KangLinDDD/ADrawer/pulls
+   - 点击 "New Pull Request"
+   - 选择你的分支
+
+## 提交规范
+
+我们使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
+
+- `feat:` 新功能
+- `fix:` Bug 修复
+- `docs:` 文档更新
+- `style:` 代码格式（不影响功能的更改）
+- `refactor:` 代码重构
+- `test:` 测试相关
+- `chore:` 构建过程或辅助工具的变动
+
+示例：
+```bash
+git commit -m "feat: add polygon vertex deletion"
+git commit -m "fix: correct text annotation vertical alignment"
+git commit -m "docs: update API reference for selection"
+```
+
+## 开发指南
+
+### 项目结构
+
+```
+src/
+├── index.ts           # 主入口
+├── modules/
+│   ├── types.ts       # 类型定义
+│   ├── viewport.ts    # 视口管理
+│   ├── annotations.ts # 标注管理
+│   ├── text-annotation.ts # 文本标注
+│   ├── renderer.ts    # 渲染器
+│   ├── events.ts      # 事件处理
+│   └── utils.ts       # 工具函数
+__tests__/             # 测试文件
+examples/              # 示例
+```
+
+### 代码风格
+
+- 使用 TypeScript
+- 2 空格缩进
+- 单引号
+- 分号必需
+- 尾随逗号
+
+### 测试
+
+- 新功能需要添加测试
+- 所有测试必须通过
+- 测试覆盖率应保持在合理水平
+
+运行测试：
+```bash
+npm test              # 运行所有测试
+npm run test:watch    # 监视模式
+npm run test:coverage # 生成覆盖率报告
+```
+
+## 发布流程
+
+维护者使用以下流程发布新版本：
+
+1. 更新 `CHANGELOG.md`
+2. 更新版本号：`npm version patch|minor|major`
+3. 推送到 GitHub：`git push && git push --tags`
+4. 创建 Release，CI 会自动发布到 npm
+
+## 行为准则
+
+- 保持友好和尊重
+- 欢迎新手，耐心解答问题
+- 专注于技术讨论
+- 接受不同的观点和经验
+
+## 获取帮助
+
+- 查看 [README](./README.md) 和 [文档](https://kanglinddd.github.io/ADrawer/)
+- 在 [GitHub Discussions](https://github.com/KangLinDDD/ADrawer/discussions) 提问
+- 加入我们的社区
+
+再次感谢你的贡献！

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,291 @@
+# Image Annotation Drawer
+
+> A lightweight, dependency-free image annotation library for the web
+
+[English](./README.md) | [中文](./README.zh-CN.md)
+
+[![npm version](https://badge.fury.io/js/image-annotation-drawer.svg)](https://www.npmjs.com/package/image-annotation-drawer)
+[![Build Status](https://github.com/KangLinDDD/ADrawer/workflows/Test/badge.svg)](https://github.com/KangLinDDD/ADrawer/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🎨 **Multiple Annotation Types**: Rectangle, Polygon, Text annotations
+- 🔍 **Viewport Operations**: Mouse wheel zoom, drag to pan
+- 🎯 **Selection & Editing**: Select, move, resize, delete annotations
+- 🎨 **Independent Styling**: Each annotation can have its own style
+- ↩️ **Undo/Redo**: Support for withdrawing operations
+- 💾 **Export**: Export annotated images in original or current view
+- ⌨️ **Keyboard Shortcuts**: Space to reset view, ESC to cancel, Delete to remove
+- 📱 **TypeScript**: Full type support
+- 🪶 **Zero Dependencies**: Lightweight, no external dependencies
+
+## Installation
+
+```bash
+npm install image-annotation-drawer
+```
+
+```bash
+yarn add image-annotation-drawer
+```
+
+```bash
+pnpm add image-annotation-drawer
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import Drawer from 'image-annotation-drawer';
+
+// Initialize
+const drawer = new Drawer({
+  id: 'container',        // Container element ID
+  drawType: 'rect',       // Default draw type: 'rect' | 'polygon' | 'drag' | 'text' | ''
+  useEvents: true,        // Enable mouse/keyboard events
+});
+
+// Load image
+drawer.drawImage('https://example.com/image.jpg');
+
+// Add text annotation programmatically
+drawer.addTextAnnotation(100, 100, 'Hello World');
+
+// Get all annotations
+const annotations = drawer.getAnnotations();
+const textAnnotations = drawer.getTextAnnotations();
+
+// Export
+drawer.exportAnnotationImage().then(base64 => {
+  console.log(base64); // data:image/jpeg;base64,...
+});
+```
+
+### HTML Setup
+
+```html
+<div id="container" style="width: 800px; height: 600px;"></div>
+```
+
+## API Reference
+
+### Constructor Options
+
+```typescript
+interface DrawerOptions {
+  id: string;                    // Container element ID (required)
+  drawType?: DrawType;           // Default draw type
+  useEvents?: boolean;           // Enable events (default: true)
+  annotationColor?: string | ColorConfig;  // Annotation colors
+  lineStyle?: LineStyle;         // Line style: 'solid' | 'dashed' | 'dotted'
+  vertexStyle?: Partial<VertexStyle>;      // Vertex style
+  textStyle?: Partial<TextStyle>;          // Text style
+}
+```
+
+### Draw Types
+
+| Type | Description |
+|------|-------------|
+| `'rect'` | Draw rectangles |
+| `'polygon'` | Draw polygons (click to add points, double-click to finish) |
+| `'drag'` | Drag to pan the image |
+| `'text'` | Click to add text annotations |
+| `''` | Default mode (selection) |
+
+### Methods
+
+#### Draw Type
+```typescript
+drawer.setDrawType('rect');           // Switch draw type
+```
+
+#### Image
+```typescript
+drawer.drawImage('image.jpg');        // Load image
+drawer.changeScale(true);             // Zoom in
+drawer.changeScale(false);            // Zoom out
+```
+
+#### Annotations
+```typescript
+// Text annotations
+drawer.addTextAnnotation(x, y, text);
+drawer.updateTextAnnotation(index, text);
+drawer.moveTextAnnotation(index, x, y);
+drawer.removeTextAnnotation(index);
+drawer.clearTextAnnotations();
+
+// Selection
+drawer.selectAnnotation(index);
+drawer.deselectAnnotation();
+drawer.deleteSelectedAnnotation();
+drawer.moveSelectedAnnotation(dx, dy);
+
+// Get data
+const annotations = drawer.getAnnotations();
+const textAnnotations = drawer.getTextAnnotations();
+const selected = drawer.getSelectedAnnotation();
+```
+
+#### Styling
+```typescript
+// Annotation colors
+drawer.setAnnotationColor('#FF0000');
+drawer.setAnnotationColor({
+  rect: '#FF0000',
+  polygon: '#00FF00',
+  default: '#0000FF'
+});
+
+// Line style
+drawer.setLineStyle('dashed');  // 'solid' | 'dashed' | 'dotted'
+
+// Vertex style
+drawer.setVertexStyle({
+  size: 8,
+  fillColor: '#FF0000',
+  strokeColor: '#FFFFFF',
+  strokeWidth: 2,
+  shape: 'circle'  // 'circle' | 'square' | 'diamond'
+});
+
+// Text style
+drawer.setTextStyle({
+  font: '16px Arial',
+  color: '#FFD700',
+  backgroundColor: 'rgba(0,0,0,0.6)',
+  padding: 6
+});
+
+// Update selected annotation's style
+drawer.updateSelectedAnnotationStyle();
+```
+
+#### Export
+```typescript
+// Export original size
+drawer.exportAnnotationImage().then(base64 => { ... });
+
+// Export current view
+drawer.exportCurrentViewImage().then(base64 => { ... });
+
+// Convert to File
+const file = drawer.base64ToFile(base64, 'annotation.jpg');
+```
+
+#### Clear & Undo
+```typescript
+drawer.clear();                    // Clear all, set draw type to ''
+drawer.clear('rect');             // Clear all, set draw type to 'rect'
+drawer.clearCanvas();             // Clear everything including image
+drawer.clearAnnotations();        // Clear annotations only, keep image
+drawer.withdraw();                // Undo last operation
+```
+
+#### Destroy
+```typescript
+drawer.destroy();                  // Clean up resources
+```
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Space` | Reset view to initial state |
+| `ESC` | Cancel current drawing / deselect |
+| `Delete` / `Backspace` | Delete selected annotation |
+| `Ctrl+Z` | Undo delete (for text annotations) |
+
+## Advanced Usage
+
+### Custom Styles Per Annotation
+
+```typescript
+// Set global style for new annotations
+drawer.setAnnotationColor('#00FF00');
+drawer.setLineStyle('dashed');
+
+// Add annotation - it will use current global style
+drawer.setDrawType('rect');
+// ... draw rectangle ...
+
+// Change style - only affects future annotations
+drawer.setAnnotationColor('#FF0000');
+drawer.setLineStyle('solid');
+
+// To update existing annotation's style:
+drawer.selectAnnotation(0);
+drawer.setAnnotationColor('#0000FF');
+drawer.updateSelectedAnnotationStyle();  // Save style to selected annotation
+```
+
+### Event Handling
+
+```typescript
+// Disable default events and handle manually
+const drawer = new Drawer({
+  id: 'container',
+  useEvents: false  // Disable default event binding
+});
+
+// Add events manually when needed
+drawer.addEventListeners();
+```
+
+### TypeScript Support
+
+```typescript
+import Drawer, { 
+  Rect, 
+  Polygon, 
+  TextAnnotation,
+  DrawerOptions,
+  VertexStyle 
+} from 'image-annotation-drawer';
+
+const options: DrawerOptions = {
+  id: 'container',
+  drawType: 'rect',
+  vertexStyle: {
+    size: 10,
+    shape: 'diamond'
+  } as Partial<VertexStyle>
+};
+
+const drawer = new Drawer(options);
+```
+
+## Browser Support
+
+- Chrome 60+
+- Firefox 60+
+- Safari 12+
+- Edge 79+
+
+## Examples
+
+- **Live Demo (English)**: https://kanglinddd.github.io/ADrawer/
+- **在线演示 (中文)**: https://kanglinddd.github.io/ADrawer/zh.html
+- **Source**: See the `examples/` directory for complete working examples.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository (https://github.com/KangLinDDD/ADrawer/fork)
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request (https://github.com/KangLinDDD/ADrawer/pulls)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.