📸 Photo Watermark CLI

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

✨ 功能特性

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

🚀 快速开始

安装

npm install -g photo-watermark-cli

基本使用

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

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

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

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

📋 完整使用指南

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

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

# 或者直接运行
photo-watermark add

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

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

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

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

# 基本用法 - 为指定目录下的照片添加水印
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. 配置管理

# 显示当前配置
photo-watermark config

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

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

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

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

# 使用交互式模式调整亮度
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 参数强制启用交互式模式

功能特点

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

操作说明

📁 文件夹选择器
当前位置: /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：旅行照片整理（推荐使用文件夹选择器）

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

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

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

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

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

场景 3：活动照片批处理

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

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

# 专门为打印优化亮度（推荐）
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. 处理缓慢

   • 大文件和高分辨率图片需要更多处理时间
   • 可以先用小批量测试

获取帮助

# 查看整体帮助
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

本地开发

# 克隆项目
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

项目结构

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

🤝 贡献

欢迎贡献代码！请查看 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 文件了解详情。

🔗 相关链接

• npm 包
• GitHub 仓库
• 问题反馈
• 更多使用示例

📊 项目统计

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

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