{"id":27382063,"url":"https://github.com/dustout/commonimageactions","last_synced_at":"2025-04-13T15:17:35.745Z","repository":{"id":285300589,"uuid":"957328560","full_name":"dustout/CommonImageActions","owner":"dustout","description":"C# library that makes common image operations like resize and shape into circle easier. Works with asp.net core url middleware via url parameters. ","archived":false,"fork":false,"pushed_at":"2025-04-13T03:09:29.000Z","size":62991,"stargazers_count":36,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T15:16:56.338Z","etag":null,"topics":["asp-net-core","c-sharp","csharp-library","gif","image-processing","jpeg","netstandard21","png","webp"],"latest_commit_sha":null,"homepage":"https://github.com/dustout/CommonImageActions","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dustout.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-30T04:49:17.000Z","updated_at":"2025-04-13T03:09:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"63b1b41d-ea2a-4a25-9363-bde0fd1c489b","html_url":"https://github.com/dustout/CommonImageActions","commit_stats":null,"previous_names":["dustout/commonimageactions"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dustout%2FCommonImageActions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dustout%2FCommonImageActions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dustout%2FCommonImageActions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dustout%2FCommonImageActions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dustout","download_url":"https://codeload.github.com/dustout/CommonImageActions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248732485,"owners_count":21152852,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asp-net-core","c-sharp","csharp-library","gif","image-processing","jpeg","netstandard21","png","webp"],"created_at":"2025-04-13T15:17:34.944Z","updated_at":"2025-04-13T15:17:35.735Z","avatar_url":"https://github.com/dustout.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Common Image Actions\n\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/dustout/CommonImageActions/dotnet.yml)\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/dustout/CommonImageActions/codeql.yml?label=Security%20Scan)\n[![NuGet Version](https://img.shields.io/nuget/v/CommonImageActions.AspNetCore)](https://www.nuget.org/packages/CommonImageActions.AspNetCore)\n![NuGet Downloads](https://img.shields.io/nuget/dt/CommonImageActions.Core)\n![GitHub License](https://img.shields.io/github/license/dustout/CommonImageActions)\n![GitHub Repo stars](https://img.shields.io/github/stars/dustout/CommonImageActions)\n\n## Summary\nA tuned image conversion library to add common image actions like resize and mask to your .Net \nand Asp.net core projects. This library is highly performant both in execution time and in memory use since it\nextends Microsoft libraries. This library should continue to increase in performance as Microsoft further\nimproves their libraries.\n\n![Animated gif that shows the functionality of common image actions](https://raw.githubusercontent.com/dustout/CommonImageActions/master/CommonImageActions.SampleAspnetCoreProject/wwwroot/test/ExplainerImage.gif)\n\n## Features\n✅ Resize images\\\n✅ Convert images to be circle or rounded rectangle\\\n✅ PDF support\\\n✅ Fast and memory efficient\\\n✅ Create user profile placeholders where background auto changes based on name\n\u003cimg src=\"https://raw.githubusercontent.com/dustout/CommonImageActions/master/CommonImageActions.SampleAspnetCoreProject/wwwroot/test/ProfilePictureStrip.png\" alt=\"Example of user profile placeholders\" style=\"height: 18px;\"\u003e\n\\\n✅ Resize through url in asp.net core (`.jpg?w=50\u0026m=zoom`) \\\n✅ Works with any project that supports .net standard \\\n✅ Fluent interface\n\n\n## Getting Started (Asp.Net Core)\n#### Install the NuGet Package\n```bash\n    Install-Package CommonImageActions.AspNetCore\n```\n\n\n#### Add UseCommonImageActions Middleware\nAdd the middleware to your startup file. Make sure that it is above `app.UseStaticFiles()`. You can watch a specific directory by setting the `PathToWatch` property in the `CommonImageActionSettings` object.\n```csharp\napp.UseCommonImageActions(\n    new CommonImageActionSettings()\n    {\n        PathToWatch = \"/test\",\n    }\n);\n```\n\n\n## Getting Started\n#### Install the NuGet Package\n```bash\n    Install-Package CommonImageActions.Core\n```\n\n#### Pass image bytes to the ImageProcessor.Process\nGet the image `bytes[]` and pass those bytes to the `ImageProcessor.Process` function\n```csharp\nbyte[] testJpg = File.ReadAllBytes(\"test.jpg\");\nvar result = await ImageProcessor.Process(testJpg)\n               .Width(100)\n               .Height(100)\n               .Mode(ImageMode.Zoom)\n               .Shape(ImageShape.Circle)\n               .ToImageAsync();\n```\n\n\n ## Code Examples (Asp.net core)\n\n #### Watch all images in all directories\n```csharp\napp.UseCommonImageActions()\n```\n\n#### Set all images to be 50x50 png images for the /logos directory\n```csharp\napp.UseCommonImageActions(\n    new CommonImageActionSettings()\n    {\n        PathToWatch = \"/logos\",\n        DefaultImageActions = new CommonImageActions.Core.ImageActions()\n        {\n            Height = 50,\n            Width = 50,\n            Format = SkiaSharp.SKEncodedImageFormat.Png\n        }\n    }\n);\n```\n\n#### Generate user placeholders and cache the response to the disk\n```csharp\n//the ChooseImageColorFromTextValue ensures that the following will have a different background color\n//https://localhost:44302/profilepicture/profile.png?t=DustinGa\n//https://localhost:44302/profilepicture/profile.png?t=DustinG\napp.UseCommonImageActions(\n    new CommonImageActionSettings()\n    {\n        PathToWatch = \"/profilepicture\",\n        IsVirtual = true,\n        UseDiskCache = true,\n        DefaultImageActions = new ImageActions()\n        {\n            Height = 50,\n            Width = 50,\n            Format = SkiaSharp.SKEncodedImageFormat.Png,\n            Shape = ImageShape.Circle,\n            AsInitials = true,\n            ChooseImageColorFromTextValue = true\n        }\n    }\n);\n```\n\n#### Add to Asp.net Core and route to an external blob storage\nLike AzureBlob or Amazon S3 or any other remote server\n```csharp\napp.UseCommonImageActions(\n    new CommonImageActionSettings()\n    {\n        PathToWatch = \"/remote\",\n        RemoteFileServerUrl = \"https://dustingamester.com/img/\"\n    }\n);\n```\n\n ## Code Examples\n #### Process an image using the fluent API\n ```csharp\n byte[] testJpg = File.ReadAllBytes(\"test.jpg\");\n var result = await ImageProcessor.Process(testJpg)\n                .Width(100)\n                .Height(100)\n                .Mode(ImageMode.Zoom)\n                .Shape(ImageShape.Circle)\n                .ToImageAsync();\n```\n\n #### Process a pdf using the fluent API\n ```csharp\n byte[] testPdf = File.ReadAllBytes(\"test.pdf\");\n var result = await PdfProcessor.Process(testPdf)\n                .Width(100)\n                .Height(100)\n                .Mode(ImageMode.Zoom)\n                .Shape(ImageShape.Circle)\n                .ToImageAsync();\n```\n\n## URL Parameters (Asp.net Core)\n| Parameter | Possible Values | Description |\n|  ------------- | ------------- | ------------- |\n| width, w  | Integer | Set the width of the image |\n| height, h | Integer | Set the height of the image |\n| mode, m | Max, Fit, Zoom, Stretch | **Max**: If both width and height are present then the image will be resized to the max of whatever parameter, and the width will scale accordingly. \u003cbr\u003e **Fit**: When both width and height are present fit the image into the container without adjusting the ratio.  \u003cbr\u003e **Zoom**: When both width and height are present zoom the image in to fill the space. \u003cbr\u003e **Stretch** (default): When both width and height are present stretch the image to fit the container. |\n| shape, s | Circle, Ellipse, RoundedRectangle  | Mask out the image to be of a certain shape. |\n| corner, cr | Integer | The corner radius when shape is RoundedRectangle. Default is 10. |\n| text, t | String | The text to display on the image |\n| initials, in | Boolean | When true will only display initials of text. For example DustinG is displayed as DG. |\n| color, c | String (ffccff or blue) | Set a color for the image |\n| textColor, tc | String (ffccff or blue) | Set the color of the text |\n| colorFromText, ft | Boolean | When true a color will be generated based on a hash of the text. The list of colors can be updated in `ImageProcessor.BackgroundColours`. |\n| format, f | Bmp, Gif, Ico, Jpeg, Png, Wbmp, Webp, Pkm, Ktx, Astc, Dng, Heif, Avif | What format to export the resulting image as. Default is png.  |\n| password, pw | String | (pdf only) password to open pdf |\n| page, p  | Integer | (pdf only) what page to render. First page is 1.|\n\n#### Modes Visualized\n![Visual that shows the different mode options](https://raw.githubusercontent.com/dustout/CommonImageActions/master/CommonImageActions.SampleAspnetCoreProject/wwwroot/test/ModeExplainer.png)\n\n\n## CommonImageActionSettings (Asp.net Core)\n| Setting | Description |\n|  ------------- | ------------- |\n| PathToWatch  | What path to watch. For example `/test` will watch for images in the test directory |\n| IsVirtual  | Avoid looking up the image and construct the image virtually (useful for profile pictures) |\n| RemoteFileServerUrl  | The URL of the remote resource to pull images from. Often a blob storage like Amazon S3 or Azure Blob |\n| UseDiskCache | When true the system will save and return cached images. This can dramatically improve performance. |\n| DiskCacheLocation | Where to store and retrieve the DiskCache images from. This directory needs to be writable. If it is not the system will print errors to the console, but will still continue to run. |\n| DefaultImageActions | Set a default image action to be used on all requests against a particular path. Useful when you want all images in a directory to be a specific dimension. |\n\n## Benchmarking\nUse [BenchmarkDotNet](https://github.com/dotnet/BenchmarkDotNet) to compare the performance between \n[Common Image Actions](https://github.com/dustout/CommonImageActions), \n[ImageSharp](https://github.com/SixLabors/ImageSharp), and \n[ImageFlowDotNet](https://github.com/imazen/imageflow-dotnet).\nThe benchmark files can be found in the /Benchmark directory if you wish to run the same test. \n\n#### Single Image\nWhen converting a single image we can see the AllocatedBytes is half of ImageSharp, and the performance is faster than\nImageFlow. \\\n![Benchmarking results of CommonImageActions against a single image](https://raw.githubusercontent.com/dustout/CommonImageActions/master/Benchmark/SingleImageResults.png)\n\n#### Multiple Images\nWhen converting multiple images we can see where CommonImageActions really shines. What takes 547ms in CommonImageActions\ntakes 4,400ms in ImageSharp and 11,430ms in ImageFlow. We can also see that the allocated memory \nis significantly less than ImageSharp. \\\n![Benchmarking results of CommonImageActions against multiple images](https://raw.githubusercontent.com/dustout/CommonImageActions/master/Benchmark/MultipleImageResults.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdustout%2Fcommonimageactions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdustout%2Fcommonimageactions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdustout%2Fcommonimageactions/lists"}