# simpleportrait

**Repository Path**: luminousone/simpleportrait

## Basic Information

- **Project Name**: simpleportrait
- **Description**: SimplePortrait is a local-first open-source Web/PWA ID photo maker with composition editing, background removal, photo compression, image resizing, and static deployment support.
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-16
- **Last Updated**: 2026-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SimplePortrait 简照

SimplePortrait 简照是一款隐私友好的轻量图片处理工具。它以浏览器本地处理为基础，提供裁剪、抠图、背景处理、尺寸调整、压缩和格式转换等常用能力，并针对证件照、考试报名照和标准化图片提供规格、构图、背景与文件大小控制。

证件照是简照最具辨识度的场景，但不是产品能力的边界。项目将逐步发展为由基础图片处理、场景模板和高级工具组成的本地图片工具。

- 当前版本：v0.3.0
- 维护者：Luminous
- 开源仓库：[Gitee · luminousone/simpleportrait](https://gitee.com/luminousone/simpleportrait)
- 联系邮箱：[Dreamluminous@163.com](mailto:Dreamluminous@163.com)

## 核心能力

### 基础图片处理

- 图片导入与浏览器相机拍摄
- 裁剪、移动、缩放和旋转
- 自动抠图、保留原背景和背景替换
- 像素、毫米尺寸与 DPI 调整
- JPG、PNG、WebP 格式输出
- 文件体积控制和独立图片压缩

### 场景化制作

- 常用证件照规格
- 英语四六级、考试报名等快捷模板
- 自定义像素、实体尺寸、DPI、构图和文件大小
- 背景颜色、透明背景和构图参考线
- 电子图片与 6 寸相纸排版输出

### 多设备界面

- 手机固定使用分步骤流程，减少复杂界面和误操作。
- 平板竖屏使用分步布局，横屏可使用专业工作台。
- 电脑普通模式使用画布与参数双栏，专业模式集中展示所有控制项。

## 分步处理流程

选择规格 → 抠图与背景 → 构图调整 → 参数与导出

分步模式遵循“先抠图、后构图”的顺序。人物主体和背景处理完成后，再调整位置和比例，可减少背景变化后重复构图。

- 已完成步骤可以从顶部直接返回。
- 当前步骤正常操作。
- 尚未完成的步骤保持禁用，避免绕过必要状态。
- 第二步和第三步共用一致的画布尺寸，并支持全屏编辑。
- 第四步使用结果信息、参数设置和小型预览，不常驻完整编辑画布。

## 独立图片工具

| 工具 | 主要用途 |
| --- | --- |
| 照片压缩 | 在保持原始像素、比例和格式的前提下控制文件体积 |
| 抠像换背景 | 自动识别连续背景，调整背景颜色、识别范围和边缘柔化 |
| 修改图片尺寸 | 调整像素、毫米尺寸、DPI、比例锁定和输出格式 |

## 页面入口

| 地址 | 用途 |
| --- | --- |
| / | 产品主页和主要功能入口 |
| /id-photo/ | 证件照与标准化图片工作台 |
| /tools/ | 独立图片工具中心 |
| /tools/compress/ | 照片压缩 |
| /tools/matting/ | 抠像换背景 |
| /tools/resize/ | 修改图片尺寸 |
| /introduction/ | 项目介绍、关于与联系（维护者、项目地址、联系方式） |
| /guide/ | 操作流程、人像建议和常见问题 |
| /about/ | 自动跳转到 /introduction/ |
| /privacy/ | 隐私政策与使用条款（单一正式文档） |
| /terms/ | 自动跳转到 /privacy/ 的使用条款部分 |

## 输入与安全范围

- 上传图片支持 JPEG、PNG 和 WebP，单张最大 30 MB。
- 图片最长边不超过 12000 px，总像素不超过 3000 万。
- 证件照输出边长为 64–6000 px。
- 工作台 DPI 为 72–600；独立尺寸工具最高支持 1200 DPI。
- JPG/WebP 质量范围为 1–100。
- 目标文件大小支持 KB 与 MB，最大 20 MB。
- 数字输入在编辑过程中允许暂时为空，离开输入框后再进行范围校验。

## 本地运行

环境要求：Node.js 22.13.0 或更高版本。

安装依赖并启动开发服务：

    npm install
    npm run dev

默认地址为 http://localhost:5173/ 。

生产构建：

    npm run build

构建完成后，静态文件位于 out 目录，可部署到 OpenResty、Nginx、1Panel 或其他兼容的静态网站服务。

## 隐私设计

- 当前版本的图片解码、裁剪、抠图、背景处理、尺寸调整、压缩、格式转换和导出默认在当前设备的浏览器内完成。
- 默认情况下，用户导入的原始图片不会因为图片处理功能而主动上传到简照业务服务器。
- 浏览器可能保存语言、界面模式、参数偏好和导出记录摘要；记录摘要不包含原始图片内容。
- 网站托管、域名解析或内容分发服务可能为安全和运维处理必要访问日志。
- 用户可以拒绝摄像头权限、停止编辑、调整记录保留设置或清除浏览器网站数据。

## 使用边界

简照提供图片处理能力和规格辅助，不代表任何政府部门、学校、考试机构、证件签发机构或材料受理平台，也不能保证处理结果通过所有第三方平台审核。模板、参考线和默认参数用于提高制作效率，提交前仍应核对目标机构当期公布的要求。

自动抠图效果会受到发丝、半透明物体、光线、背景反差和原图清晰度影响。复杂图片应检查边缘，必要时调整识别范围、重新处理或保留原背景。

## 测试

    npm run test:core
    node tests/mode-matrix.e2e.mjs
    npm run build

重点检查尺寸换算、步骤权限、状态同步、数字输入、移动端键盘、响应式布局、透明背景输出和公开页面语言状态。

## 后续方向

1. 扩充考试、学籍、简历、护照、签证、头像和平台图片模板。
2. 优化复杂边缘的本地抠图。
3. 增加批量处理、批量规格转换和高级模板。
4. 探索实时背景处理和更多本地图片工具。
5. 在网页流程稳定后逐步适配小程序、移动端和桌面端。

## 许可证

项目采用 [Apache License 2.0](LICENSE) 开源。使用、修改和分发时请保留许可证与版权声明。

SimplePortrait 简照由 Luminous 设计与维护。欢迎通过开源仓库提交问题、建议和改进。