Please see the Example A.401 - "Customize Piczard / Custom filters"
There are several Filters available in Piczard, such as ResizeConstraint (to automatically resize images), or CropConstraint (to crop images).
Many other Filters can be created by inheriting from the abstract class ImageProcessingFilter.
Basically there are three ways to develop a custom image processing filter:
- By creating a totally custom filter that inherits directly from ImageProcessingFilter.
For more information: Create a totally custom filter
- By inheriting from an existing filter (e.g. from TextWatermark or ColorMatrixFilter).
For more information: Inherit from an existing filter
- By creating a custom filter that simply aggregates one or more existing filters.
For more information: Aggregate one or more filters
|Please see the MyCustomFilter1 class contained in the ~/App_Code folder of ExampleSet A|
Every class that inherits from the abstract class ImageProcessingFilter must implement the Apply method.
This method is the one that has the task of transforming the source image into the final image.
For example, if you are developing a custom watermark filter, then you have to put the code responsable of writing the watermark within the Apply method
The method receives as input an instance of the ImageProcessingActionExecuteArgs
- You don't need to dispose the previous value (Piczard automatically disposes it)
- The new value cannot be null
- The PixelFormat of the new image must be equal to CommonData.DefaultPixelFormat
|Please see the MyInheritedFilter class contained in the ~/App_Code folder of ExampleSet A|
It is possible to create a new image filter by inheriting from an existing one.
However, please note that you can not inherit from all ImageProcessingFilter.
For example, you cannot inherit from CropConstraint (FixedCropConstraint, FixedAspectRatioCropConstraint, FreeCropConstraint) or ResizeConstraint (ScaledResizeConstraint, FixedResizeConstraint).
|Please see the MyAggretatedFilters class contained in the ~/App_Code folder of ExampleSet A|
You can create a custom filter that simply applies other pre-existing filters.
In this case you have to override the LoadImageProcessingActions method.
This method receives as input an instance of the ImageProcessingActionLoadArgs.
You can use the method LoadImageProcessingActions to add one or more filters to the processing workflow.
|An aggregate filter||Copy Code|
public class MyAggretatedFilters
protected override void LoadImageProcessingActions(ImageProcessingActionLoadArgs args)
// Add the filters...
// Filter #1
args.LoadImageProcessingActions(new FixedCropConstraint(300, 200));
// Filter #2
protected override void Apply(ImageProcessingActionExecuteArgs args)
Once you have developed a custom filter, you can use it exactly in the same way you use the other existing Piczard filters.
new MyAggretatedFilters().SaveProcessedImageToFileSystem("Source.png", "Output.jpg");
If you plan to develop a custom ImageProcessingFilter for color manipulation then you may consider inherit from this class.
In this way your new filter will benefit from the optimizations provided by Piczard in order to save computer resources (CPU / RAM).
If you inherit from ColorMatrixFilter, then you can override the GetColorMatrices method in order to pass to the parent class the necessary ColorMatrix objects.
Each color matrix will be applied in chain - one after the other - to the image.
|For information on how Piczard handles the image background color please see: Image Processing Job (Controlling the background color of images generated by Piczard)|
An ImageProcessingFilter can programmatically apply the background color in 2 ways:
- By invoking the ApplyImageBackColor method of the ImageProcessingActionExecuteArgs class (please see: ImageProcessingFilter.Apply method)
In this case be sure that the image back color has not been already applied (ImageProcessingActionExecuteArgs.AppliedImageBackColorValue.HasValue must be false).
If the filter tries to apply more than one time the background color, an Exception is raised.
- By adding an instance of the ApplyImageBackColorAction class to the ImageProcessingActionLoadArgs.Actions property (please see: ImageProcessingFilter.LoadImageProcessingActions method)
Note: The ApplyImageBackColorAction class automatically checks if the background color has been already applied (no Exception is raised).
In every case, when an image is processed, the background color is always applied only one time.
It's not possible to apply the background color more than one time.
If your filter generate a new System.Drawing.Image object, then it is suggested to add the following code in the ImageProcessingFilter.Apply method (before the new image object is modified):
|Suggested optimization||Copy Code|
if ((args.IsLastAction) && (!args.AppliedImageBackColorValue.HasValue))
- g is a System.Drawing.Graphics object able to maniplate the new Image.
This code allows to save CPU and RAM by automatically appling the image background color if necessary.
|Please see the "MyCustomFilter1" class contained in the "~/App_Code" directory of the ExampleSet A.|