From a7fdf6011bec1b4348ea62feb4291c4b3b56c823 Mon Sep 17 00:00:00 2001 From: Andrew Date: Wed, 27 May 2026 21:49:53 +0300 Subject: [PATCH] readme updated due to lib changes --- README.md | 248 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 221 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 82997ea..81bfae3 100644 --- a/README.md +++ b/README.md @@ -6,46 +6,240 @@ ![GitHub last commit](https://img.shields.io/github/last-commit/Geckon01/Watermark.Net?display_timestamp=author) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/e6340e249ad743bc99c1745aaa0a9838)](https://app.codacy.com/gh/Geckon01/Watermark.Net/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) -Watermark.Net is open source .NET library for adding text and image watermarks to images. Built on SixLabors.ImageSharp, it provides a simple yet comprehensive API for all your watermarking needs. +**Watermark.Net** is an open-source .NET library for programmatically adding text and image watermarks to images. Built on [SixLabors.ImageSharp](https://github.com/SixLabors/ImageSharp), it provides a clean, extensible API for all your watermarking needs — from a single file to entire directory batches. Whether you need to protect copyrights, brand your media, or mark drafts, Watermark.Net makes image watermarking in C# simple and efficient. ### Features - - 🖼️ Multi-format support - Works with JPEG, PNG, BMP, GIF - - ✏️ Text watermarks - Custom fonts, colors, sizes, rotations, and positioning - - 🖌️ Image watermarks - PNG transparency support, scaling, and opacity control - - 🧩 Positioning - 9 preset positions - - 🧱 Pave mode - Tile watermarks across entire image - - 📁 Batch processing - Process entire directories with single method call -# Quick Start +- 🖼️ **Multi-format support** — JPEG, PNG, BMP, GIF +- ✏️ **Text watermarks** — custom fonts, colors, sizes, rotation, and 9-zone positioning +- 🖌️ **Image watermarks** — PNG transparency, scaling, and opacity control (0.0–1.0) +- 🧱 **Pave (tiling) mode** — repeat the watermark across the entire image surface +- 🧩 **9 preset positions** — TopLeft, TopCenter, TopRight, CenterLeft, Center, CenterRight, BottomLeft, BottomCenter, BottomRight +- 🎨 **Custom styling** — background color, opacity, rotation angle, and padding +- 📁 **Batch processing** — watermark all images in a directory with a single method call +- 🔌 **Dependency injection ready** — `IFileManager` abstraction for testing and custom file I/O +- 🔄 **Backward compatible** — legacy `Watermarker` API still supported (marked as `[Obsolete]`) + +--- + +## Installation + +Install the [NuGet package](https://www.nuget.org/packages/Watermark.Net/): + +```bash +dotnet add package Watermark.Net +``` + +Requires **.NET 8** or later. + +--- + +## Quick Start + +### Add a Text Watermark -### Add Text Watermark ```csharp -var watermarker = new Watermarker("output"); -var textWatermark = new TextWatermark +using SixLabors.Fonts; +using SixLabors.ImageSharp; +using Watermark.Net.src.WatermarkNet.Core; +using Watermark.Net.src.WatermarkNet.Enums; +using Watermark.Net.src.WatermarkNet.Models.Definitions; + +var pipeline = new WatermarkPipeline(new FileManager(), new ImageRenderer()); + +var watermark = new TextWatermark { Text = "WATERMARK", Font = SystemFonts.CreateFont("Arial", 36), - Color = Color.White, - Position = ImagePosition.BottomRight, - Scale = 0.5f + Layout = { Position = ImagePosition.BottomRight, Scale = 0.5f }, + Style = { Color = Color.White } }; -var result = watermarker.ProcessImage("input.jpg", textWatermark); // Saves to output/input.jpg +ResultImage result = pipeline.ProcessImage("input.jpg", "output", watermark); +Console.WriteLine($"Saved to: {result.Path}"); ``` -### Add Image Watermark + +### Add an Image Watermark + ```csharp -var watermarker = new Watermarker("output"); -var imageWatermark = new ImageWatermark("logo.png") +using SixLabors.ImageSharp; +using Watermark.Net.src.WatermarkNet.Core; +using Watermark.Net.src.WatermarkNet.Enums; +using Watermark.Net.src.WatermarkNet.Models.Definitions; + +var pipeline = new WatermarkPipeline(new FileManager(), new ImageRenderer()); + +var watermark = new ImageWatermark { - Opacity = 0.7f, - Scale = 0.3f, - Position = ImagePosition.Center, - Pave = true + ImagePath = "logo.png", + Layout = { Scale = 0.3f, Position = ImagePosition.Center }, + Style = { Opacity = 0.7f, Pave = true } }; -var results = watermarker.ProcessDirectory("images", imageWatermark); +List results = pipeline.ProcessDirectory("images", "output", watermark); +Console.WriteLine($"Processed {results.Count} images"); ``` -# Contributing -Contributions are welcome! Just make sure that all tests pass before open PR. -# License -Watermark.Net is licensed under the MIT License. + +--- + +## Architecture + +Watermark.Net follows a clean **pipeline architecture** with clear separation of concerns: + +``` +┌──────────────────────────────────────┐ +│ WatermarkPipeline │ ← Orchestrator layer +│ (coordinates I/O and rendering) │ +├──────────────────────────────────────┤ +│ IFileManager / FileManager │ ← File I/O abstraction +│ (loading, saving, enumeration) │ +├──────────────────────────────────────┤ +│ ImageRenderer │ ← Pure rendering engine +│ (image processing, no I/O) │ +└──────────────────────────────────────┘ +``` + +- **[`WatermarkPipeline`](Watermark.Net/src/WatermarkNet.Common/WatermarkPipeline.cs)** — the main entry point that orchestrates file operations and rendering. +- **[`IFileManager`](Watermark.Net/src/WatermarkNet.Common/IFileManager.cs)** / **[`FileManager`](Watermark.Net/src/WatermarkNet.Common/FileManager.cs)** — abstracts all file system I/O. Swap this for custom storage or unit testing. +- **[`ImageRenderer`](Watermark.Net/src/WatermarkNet.Common/ImageRenderer.cs)** — a pure image processing engine. Accepts in-memory `Image` objects, returns processed `Image` instances. No file I/O dependency. + +--- + +## Configuration Reference + +### [`WatermarkLayout`](Watermark.Net/src/WatermarkNet.Models/Layout/WatermarkLayout.cs) + +Controls *where* and *how big* the watermark appears. + +| Property | Type | Default | Description | +|--------------|----------------|----------|--------------------------------------------| +| `Position` | `ImagePosition`| `TopLeft`| One of 9 predefined positions | +| `Scale` | `float` | `0` | Scale factor relative to image size | +| `RotateAngle`| `int` | `0` | Rotation angle in degrees | +| `Padding` | `float` | `0` | Padding space around the watermark (px) | + +### [`WatermarkStyle`](Watermark.Net/src/WatermarkNet.Models/Styling/WatermarkStyle.cs) + +Controls *how* the watermark looks. + +| Property | Type | Default | Description | +|-----------|---------|----------|------------------------------------------------| +| `Opacity` | `float` | `0` | Transparency level — `0.0` (transparent) to `1.0` (opaque) | +| `Pave` | `bool` | `false` | When `true`, tiles the watermark across the image | +| `Color` | `Color` | `default`| Background or text color | + +### [`ImagePosition`](Watermark.Net/src/WatermarkNet.Enums/ImagePosition.cs) + +All 9 available positions: + +| Name | Description | +|----------------|--------------------| +| `TopLeft` | Top-left corner | +| `TopCenter` | Top-center | +| `TopRight` | Top-right corner | +| `CenterLeft` | Middle-left | +| `Center` | Exact center | +| `CenterRight` | Middle-right | +| `BottomLeft` | Bottom-left corner | +| `BottomCenter` | Bottom-center | +| `BottomRight` | Bottom-right corner| + +### Model types + +| Type | Description | +|---------------------------------------------------|------------------------------------------------| +| [`TextWatermark`](Watermark.Net/src/WatermarkNet.Models/Definitions/TextWatermark.cs) | Text watermark configuration (`Text`, `Font`) | +| [`ImageWatermark`](Watermark.Net/src/WatermarkNet.Models/Definitions/ImageWatermark.cs) | Image watermark configuration (`ImagePath`) | +| [`ResultImage`](Watermark.Net/src/WatermarkNet.Models/Definitions/ResultImage.cs) | Output result (`.Image` + `.Path`) | +| [`IWatermarkDefinition`](Watermark.Net/src/WatermarkNet.Models/Definitions/IWatermarkDefinition.cs) | Base interface for custom watermark definitions | + +--- + +## Advanced Usage + +### Pave (Tiling) Mode + +Tile the watermark across every position on the image: + +```csharp +var watermark = new TextWatermark +{ + Text = "DRAFT", + Font = SystemFonts.CreateFont("Arial", 36), + Style = { Color = Color.Red, Pave = true }, + Layout = { Scale = 0.3f } +}; +``` + +### Opacity Control + +Create a subtle, semi-transparent watermark: + +```csharp +var watermark = new ImageWatermark +{ + ImagePath = "logo.png", + Style = { Opacity = 0.3f }, // 30% opacity + Layout = { Position = ImagePosition.Center, Scale = 0.5f } +}; +``` + +### Custom Positioning & Rotation + +Place a rotated watermark with padding: + +```csharp +var watermark = new TextWatermark +{ + Text = "CONFIDENTIAL", + Font = SystemFonts.CreateFont("Arial", 24), + Layout = + { + Position = ImagePosition.TopLeft, + RotateAngle = 45, + Padding = 20 + } +}; +``` + +### Dependency Injection + +Integrate with your DI container for better testability: + +```csharp +services.AddSingleton(); +services.AddSingleton(); +services.AddTransient(); +``` + +### Batch Directory Processing + +Process all images in a directory with a single call: + +```csharp +var results = pipeline.ProcessDirectory("input_photos", "watermarked", textWatermark); + +foreach (var result in results) +{ + Console.WriteLine($"✓ {result.Path}"); +} +``` + +--- + +## Contributing + +Contributions are welcome! To ensure a smooth collaboration: + +1. **Fork** the repository and create a feature branch. +2. **Write tests** for any new functionality (see the [`UnitTest`](UnitTest/UnitTest.cs) project). +3. **Run all tests** before opening a pull request — make sure they pass. +4. **Open a PR** with a clear description of the changes. + +All tests use sample images located in [`UnitTest/TestImages/`](UnitTest/TestImages/). + +--- + +## License + +Watermark.Net is licensed under the [MIT License](LICENSE).