From d5e3bda46b70719b98f9cd865e69e0d43d600589 Mon Sep 17 00:00:00 2001 From: Salih Date: Mon, 22 May 2023 19:07:05 +0300 Subject: [PATCH] Add Imaging Doc --- docs/en/Imaging.md | 234 ++++++++++++++++++++++++++++++++++++++++++ docs/en/docs-nav.json | 4 + 2 files changed, 238 insertions(+) create mode 100644 docs/en/Imaging.md diff --git a/docs/en/Imaging.md b/docs/en/Imaging.md new file mode 100644 index 0000000000..157809ab72 --- /dev/null +++ b/docs/en/Imaging.md @@ -0,0 +1,234 @@ +# Imaging +The ABP Framework provides an abstraction to work with image compress/resize. Having such an abstraction has some benefits; + +* You can write library independent code. Therefore, you can change the underlying library with the minimum effort and code change. +* You can use the predefined image resizer/compressor defined in the ABP without worrying about the underlying library's internal details. + +> The image resizer/compressor system is designed to be extensible. You can implement your own image resizer/compressor contributor and use it in your application. + +## IImageResizer + +You can inject `IImageResizer` and use it for image resize operations. Here is the available operations in the `IImageResizer` interface. + +```csharp +public interface IImageResizer +{ + Task> ResizeAsync(Stream stream, ImageResizeArgs resizeArgs, [CanBeNull]string mimeType = null, CancellationToken cancellationToken = default); + + Task> ResizeAsync(byte[] bytes, ImageResizeArgs resizeArgs, [CanBeNull] string mimeType = null, CancellationToken cancellationToken = default); +} +``` + +Usage example: + +```csharp +var result = await _imageResizer.ResizeAsync( + stream, + new ImageResizeArgs + { + Width = 100, + Height = 100, + Mode = ImageResizeMode.Crop + }, + mimeType: "image/jpeg" +); +``` + +## IImageCompressor + +You can inject `IImageCompressor` and use it for image compression operations. Here is the available operations in the `IImageCompressor` interface. + +```csharp +public interface IImageCompressor +{ + Task> CompressAsync( + Stream stream, + [CanBeNull] string mimeType = null, + CancellationToken cancellationToken = default); + + Task> CompressAsync( + byte[] bytes, + [CanBeNull] string mimeType = null, + CancellationToken cancellationToken = default); +} +``` + +Usage example: + +```csharp +var result = await _imageCompressor.CompressAsync( + stream, + mimeType: "image/jpeg" +); +``` + +## ImageProcessResult + +The `ImageProcessResult` is a generic class that is used to return the result of the image processing operations. It has the following properties: + +* `Result`: The processed image stream or byte array. +* `IsSuccess`: Indicates whether the operation is successful or not. (If the operation is not successful, the `Result` property will be your input stream or byte array.) + +## ImageResizeArgs + +The `ImageResizeArgs` is a class that is used to define the resize operation parameters. It has the following properties: + +* `Width`: The width of the resized image. +* `Height`: The height of the resized image. +* `Mode`: The resize mode. (See the [ImageResizeMode](#imageresizemode) section for more information.) + +## ImageResizeMode + +The `ImageResizeMode` is an enum that is used to define the resize mode. It has the following values: + +```csharp +public enum ImageResizeMode +{ + None, + Stretch, + BoxPad, + Min, + Max, + Crop, + Pad, + Default +} +``` + +## IImageResizerContributor + +The `IImageResizerContributor` is an interface that is used to implement a custom image resizer. It has the following method: + +```csharp +public interface IImageResizerContributor +{ + Task> TryResizeAsync(Stream stream, ImageResizeArgs resizeArgs, string mimeType = null, CancellationToken cancellationToken = default); + + Task> TryResizeAsync(byte[] bytes, ImageResizeArgs resizeArgs, string mimeType = null, CancellationToken cancellationToken = default); +} +``` + +## IImageCompressorContributor + +The `IImageCompressorContributor` is an interface that is used to implement a custom image compressor. It has the following method: + +```csharp +public interface IImageCompressorContributor +{ + Task> TryCompressAsync(Stream stream, string mimeType = null, CancellationToken cancellationToken = default); + Task> TryCompressAsync(byte[] bytes, string mimeType = null, CancellationToken cancellationToken = default); +} +``` + +## ImageContributorResult + +The `ImageContributorResult` is a generic class that is used to return the result of the image processing operations. It has the following properties: + +* `Result`: The processed image stream or byte array. +* `IsSuccess`: Indicates whether the operation is successful or not. (If the operation is not successful, the `Result` property will be your input stream or byte array.) +* `IsSupported`: Indicates whether the contributor supports the given image or not. (If the contributor does not support the given image, the `Result` property will be your input stream or byte array.) +* `Exception`: The exception that is thrown during the image processing operation. (If the operation is successful, this property will be null.) + +## Configuration + +### ImageResizeOptions + +`ImageResizeOptions` is used to configure the image resize system. It has the following properties: + +* `DefaultResizeMode`: The default resize mode. (Default: `ImageResizeMode.None`) + +## Magick.NET + +Add the `Volo.Abp.Imaging.MagickNet` NuGet package to your project and use the `AbpImagingMagickNetModule` module. + +```csharp +[DependsOn(typeof(AbpImagingMagickNetModule))] +public class MyModule : AbpModule +{ + //... +} +``` + +### Configuration + +#### MagickNetCompressOptions + +`MagickNetCompressOptions` is used to configure the Magick.NET image compression system. It has the following properties: + +* `OptimalCompression`: Indicates whether the optimal compression is enabled or not. (Default: `false`) +* `IgnoreUnsupportedFormats`: Indicates whether the unsupported formats are ignored or not. (Default: `false`) +* `Lossless`: Indicates whether the lossless compression is enabled or not. (Default: `false`) + +## ImageSharp + +Add the `Volo.Abp.Imaging.ImageSharp` NuGet package to your project and use the `AbpImagingImageSharpModule` module. + +```csharp +[DependsOn(typeof(AbpImagingImageSharpModule))] +public class MyModule : AbpModule +{ + //... +} +``` + +### Configuration + +#### ImageSharpCompressOptions + +`ImageSharpCompressOptions` is used to configure the ImageSharp image compression system. It has the following properties: + +* `JpegQuality`: The JPEG quality. (Default: `60`) +* `PngCompressionLevel`: The PNG compression level. (Default: `PngCompressionLevel.Level9`) +* `PngIgnoreMetadata`: Indicates whether the PNG metadata is ignored or not. (Default: `true`) +* `WebpQuality`: The WebP quality. (Default: `60`) + +## AspNetCore + +Add the `Volo.Abp.Imaging.AspNetCore` NuGet package to your project and use the `AbpImagingAspNetCoreModule` module. + +```csharp +[DependsOn(typeof(AbpImagingAspNetCoreModule))] +public class MyModule : AbpModule +{ + //... +} +``` + +### CompressImageAttribute + +The `CompressImageAttribute` is used to compress the image before requesting the action. IFormFile, IRemoteStreamContent, Stream and IEnumrable types are supported. It has the following properties: + +* `Parameters`: The parameters that are used to configure the image compression system. (Optional. This applies to all parameters if left blank.) + +Usage example: + +```csharp + +[CompressImage] +[HttpPost] +public async Task Upload(IFormFile file) +{ + //... +} +``` + +### ResizeImageAttribute + +The `ResizeImageAttribute` is used to resize the image before requesting the action. IFormFile, IRemoteStreamContent, Stream and IEnumrable types are supported. It has the following properties: + +* `Parameters`: The parameters that are used to configure the image resize system. (Optional. This applies to all parameters if left blank.) +* `Width`: The width of the resized image. +* `Height`: The height of the resized image. +* `Mode`: The resize mode. (See the [ImageResizeMode](#imageresizemode) section for more information.) + +Usage example: + +```csharp + +[ResizeImage(Width = 100, Height = 100, Mode = ImageResizeMode.Crop)] +[HttpPost] +public async Task Upload(IFormFile file) +{ + //... +} +``` \ No newline at end of file diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index ad2bbc652b..9b3a22b416 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -458,6 +458,10 @@ { "text": "Virtual File System", "path": "Virtual-File-System.md" + }, + { + "text": "Imaging", + "path": "Imaging.md" } ] },