photo-watermark-cli/README.md

A modern TypeScript CLI tool to add timestamp watermarks to photos with intelligent size scaling

# 📸 Photo Watermark CLI

一个现代化的 TypeScript CLI 工具，用于智能地为照片添加时间水印。

[![npm version](https://badge.fury.io/js/photo-watermark-cli.svg)](https://badge.fury.io/js/photo-watermark-cli)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ 功能特性

- 🎯 **智能相对大小算法** - 根据图片分辨率自动调整水印大小
- 📸 **EXIF 时间提取** - 优先使用照片的实际拍摄时间
- 🎨 **多种水印位置** - 支持四个角落的灵活定位
- 🖼️ **全格式支持** - JPG、PNG、TIFF、WebP、BMP
- ⚡ **高性能处理** - 基于 Sharp 库的快速图像处理
- 🔧 **配置持久化** - 个人设置自动保存
- 💻 **现代 TypeScript** - 完全类型安全的开发体验
- 🎪 **交互式界面** - 友好的命令行交互体验
- 📁 **可视化文件夹选择器** - 无需手动输入路径，交互式浏览文件系统
- 🌟 **智能亮度调整** - 专为打印优化，解决打印照片偏暗问题

## 🚀 快速开始

### 安装

```bash
npm install -g photo-watermark-cli
```

### 基本使用

```bash
# 交互式模式（推荐）- 使用可视化文件夹选择器
photo-watermark add

# 仅调整照片亮度（专为打印优化）
photo-watermark brighten

# 命令行模式
photo-watermark add -d /path/to/photos -o /path/to/output

# 列出目录下的图片（使用文件夹选择器）
photo-watermark list
```

## 📋 完整使用指南

### 1. 交互式模式（推荐新手使用）

```bash
# 启动交互式界面（包含可视化文件夹选择器）
npm start

# 或者直接运行
photo-watermark add
```

这将启动交互式界面，首先显示一个可视化的文件夹选择器，您可以：

- 📁 使用方向键浏览文件夹
- 🏠 快速跳转到用户主目录
- 📂 快速跳转到当前工作目录
- ⬆️ 返回上级目录
- ✅ 选择当前目录

选择目录后，继续进行水印配置。

### 2. 命令行模式（推荐高级用户）

```bash
# 基本用法 - 为指定目录下的照片添加水印
photo-watermark add -d /path/to/your/photos

# 指定自定义输出目录（高级用法）
photo-watermark add -d /path/to/photos -o /path/to/output

# 自定义时间格式
photo-watermark add -d /path/to/photos -f "YYYY年MM月DD日 HH:mm"

# 同时调整亮度和添加水印
photo-watermark add -d /path/to/photos -b 1.3

# 仅调整照片亮度（专为打印优化）
photo-watermark brighten -d /path/to/photos -b 1.3

# 启用交互式模式
photo-watermark add -d ./photos -i

# 列出目录下所有支持的图片文件（使用文件夹选择器）
photo-watermark list

# 或者直接指定目录路径
photo-watermark list /path/to/photos
```

### 输出方式说明

默认情况下，交互式模式会提供两种输出方式选择：

1. **推荐方式**：在原目录下创建 `watermarked` 文件夹

   - 🛡️ 安全，不会覆盖原文件
   - 📁 自动保持原有目录结构
   - 🔍 便于对比处理前后的效果

2. **覆盖方式**：直接覆盖原文件
   - 💾 节省存储空间
   - ⚠️ 需要提前备份重要照片

### 3. 配置管理

```bash
# 显示当前配置
photo-watermark config

# 重置配置
photo-watermark config --reset

# 显示配置文件路径
photo-watermark config --path
```

### 4. 亮度调整功能（专为打印优化）

本工具新增了专门的亮度调整功能，解决照片打印时偏暗的问题：

```bash
# 使用交互式模式调整亮度
photo-watermark brighten

# 命令行模式调整亮度
photo-watermark brighten -d /path/to/photos -b 1.3

# 覆盖原文件（请先备份）
photo-watermark brighten -d /path/to/photos -b 1.3 --overwrite
```

#### 推荐亮度值

- **打印用途**: 1.2-1.5 (解决打印偏暗)
- **屏幕显示偏暗**: 1.3-1.6
- **轻微增亮**: 1.1-1.2
- **显著增亮**: 1.5-2.0

#### 功能特点

- 🖨️ **打印优化**: 专门解决照片打印时偏暗的问题
- 🎯 **智能处理**: 基于 Sharp 库的高质量图像处理
- 📁 **灵活输出**: 可选择创建新文件夹或覆盖原文件
- 🔧 **质量控制**: 可调整输出图片质量
- 🚀 **高效批处理**: 支持大量照片的快速处理

## 📁 可视化文件夹选择器

本工具新增了可视化文件夹选择器功能，让您无需手动输入路径即可轻松选择目标文件夹。

### 启动方式

1. **自动启动**：直接运行 `photo-watermark add` 或 `photo-watermark list` 不带参数时自动启动
2. **交互式模式**：使用 `-i` 参数强制启用交互式模式

### 功能特点

- 🧭 **可视化导航**：使用方向键和回车键浏览文件系统
- 🏠 **快捷跳转**：一键跳转到用户主目录
- 📂 **当前目录**：快速返回到当前工作目录
- ⬆️ **上级目录**：轻松返回上级目录
- 🔍 **智能过滤**：自动隐藏系统隐藏文件夹
- 📍 **路径显示**：实时显示当前浏览位置

### 操作说明

```text
📁 文件夹选择器
当前位置: /Users/username/Pictures
使用方向键选择，Enter确认

? 请选择一个选项:
❯ 📁 .. (返回上级目录)
  🏠 用户主目录
  📂 当前工作目录
  📁 旅行照片2024
  📁 家庭聚会
  📁 工作项目
  ✅ 选择当前目录: /Users/username/Pictures
```

- **↑↓ 方向键**：浏览选项
- **Enter**：确认选择
- **Ctrl+C**：退出程序

## 🎨 配置选项

### 时间来源

1. **EXIF 信息**：优先使用照片的拍摄时间（DateTimeOriginal、DateTime、DateTimeDigitized）
2. **文件时间**：如果没有 EXIF 信息，使用文件的修改时间

### 时间格式

- `YYYY-MM-DD HH:mm:ss` (默认): 2024-12-01 14:30:25
- `YYYY年MM月DD日`: 2024 年 12 月 01 日
- `MM/DD/YYYY HH:mm`: 12/01/2024 14:30
- `DD.MM.YYYY`: 01.12.2024

### 水印位置

- **左下角** (bottom-left) - 默认位置
- **右下角** (bottom-right)
- **左上角** (top-left)
- **右上角** (top-right)

### 样式选项

- **字体大小**: 12-48 像素，智能相对缩放
- **字体颜色**: 白色、黑色、红色、蓝色、绿色、黄色
- **文字阴影**: 增强复杂背景下的可读性
- **图片质量**: 1-100，控制输出文件质量
- **照片亮度**: 0.1-3.0，1.0 为原始亮度，大于 1.0 增亮（专为解决打印偏暗问题）

## 🔧 智能相对大小算法

本工具的核心特性是智能相对大小算法，确保水印在不同分辨率的图片上都有合适的大小：

| 分辨率             | 字体大小 | 缩放比例 |
| ------------------ | -------- | -------- |
| 640x480 (标清)     | 12px     | 0.25x    |
| 1920x1080 (全高清) | 14px     | 0.56x    |
| 3840x2160 (4K)     | 27px     | 1.13x    |
| 7680x4320 (8K)     | 54px     | 2.25x    |

## 📁 支持的图片格式

- **JPEG** (.jpg, .jpeg) - 最常用的照片格式
- **PNG** (.png) - 支持透明度的图片格式
- **TIFF** (.tiff) - 高质量专业图像格式
- **WebP** (.webp) - 现代网络优化格式
- **BMP** (.bmp) - Windows 位图格式

## 💡 使用场景示例

### 场景 1：旅行照片整理（推荐使用文件夹选择器）

```bash
# 使用可视化文件夹选择器（推荐）
photo-watermark add
# 启动后通过界面选择目标文件夹

# 传统命令行方式
photo-watermark add -d ~/Pictures/旅行2024 -o ~/Pictures/旅行2024_带水印
```

### 场景 2：快速预览目录下的图片

```bash
# 使用文件夹选择器浏览并查看图片列表
photo-watermark list
# 可以轻松切换不同目录进行查看

# 直接指定目录
photo-watermark list ~/Pictures/活动照片
```

### 场景 3：活动照片批处理

```bash
# 交互式模式：选择在原目录下创建 "watermarked" 文件夹
photo-watermark add
# 通过文件夹选择器找到活动照片目录，设置时间格式为 "YYYY年MM月DD日 HH:mm"
```

### 场景 4：照片打印前亮度优化

```bash
# 专门为打印优化亮度（推荐）
photo-watermark brighten
# 通过交互式界面选择目录，设置亮度为 1.3

# 命令行快速处理
photo-watermark brighten -d ~/Pictures/待打印 -b 1.3

# 同时调整亮度和添加水印
photo-watermark add -d ~/Pictures/照片 -b 1.2
```

## ⚠️ 注意事项

1. **备份重要照片**：建议在处理重要照片前先做备份
2. **预览功能**：使用 `--dry-run` 选项可以预览效果而不修改文件
3. **输出目录**：如果指定输出目录，会保持原有的目录结构
4. **性能**：使用 Sharp 库，处理速度较快，但大量高分辨率照片可能需要一些时间
5. **权限**：确保对目标目录有读写权限

## 🔧 故障排除

### 常见问题

1. **"目录不存在"错误**

   - 检查路径是否正确
   - 使用绝对路径或相对于当前目录的正确路径

2. **"权限被拒绝"错误**

   - 检查目录和文件的读写权限
   - 在 macOS/Linux 上可能需要使用 `sudo`

3. **"未找到图片文件"**

   - 确认目录下有支持的图片格式
   - 使用 `list` 命令检查可识别的文件

4. **处理缓慢**
   - 大文件和高分辨率图片需要更多处理时间
   - 可以先用小批量测试

### 获取帮助

```bash
# 查看整体帮助
photo-watermark --help

# 查看特定命令帮助
photo-watermark add --help
photo-watermark brighten --help
photo-watermark list --help
photo-watermark config --help
```

## 🛠️ 开发指南

### 环境要求

- Node.js >= 18.0.0
- npm >= 8.0.0
- TypeScript >= 5.0.0

### 本地开发

```bash
# 克隆项目
git clone https://github.com/taosiqi/photo-watermark-cli.git
cd photo-watermark-cli

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建项目
npm run build

# 运行测试
npm run test
```

### 项目结构

```text
├── src/
│   ├── types.ts          # TypeScript 类型定义
│   ├── bin/
│   │   └── watermark.ts  # CLI 入口点
│   └── lib/
│       ├── config.ts     # 配置管理
│       ├── scanner.ts    # 图片扫描
│       └── watermark.ts  # 核心水印处理
├── dist/                 # 构建输出目录
├── tsconfig.json         # TypeScript 配置
└── package.json          # 项目配置
```

## 🤝 贡献

欢迎贡献代码！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细指南。

### 开发流程

1. Fork 项目
2. 创建功能分支：`git checkout -b feature/amazing-feature`
3. 提交更改：`git commit -m 'Add amazing feature'`
4. 推送分支：`git push origin feature/amazing-feature`
5. 提交 Pull Request

## 📝 许可证

MIT License - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🔗 相关链接

- [npm 包](https://www.npmjs.com/package/photo-watermark-cli)
- [GitHub 仓库](https://github.com/taosiqi/photo-watermark-cli)
- [问题反馈](https://github.com/taosiqi/photo-watermark-cli/issues)
- [更多使用示例](EXAMPLES.md)

## 📊 项目统计

- 🎯 智能相对大小算法确保水印视觉一致性
- 📁 可视化文件夹选择器提升用户体验
- 📦 包大小：~19KB（压缩后）
- ⚡ 支持所有主流图片格式
- 🔧 完全类型安全的 TypeScript 实现
- 🌟 现代化的 CLI 交互体验

---

⭐ 如果这个项目对你有帮助，请给它一个星星！