CodeCarvings Piczard V1.2 Help
How To Develop A Custom Image Processing Filter
Send Feedback
Extending Piczard > Filters > How To Develop A Custom Image Processing Filter

Glossary Item Box


  1. Introduction
  2. Create a totally custom filter
  3. Inherit from an existing filter
  4. Aggregate one or more filters
  5. How to use a custom filter
  6. Information for filter authors about color filters
  7. Information for filter authors about the image background color


Please see the Example A.401 - "Customize Piczard / Custom filters"



1. Introduction

The key element that allows to process images with Piczard is the Filter, represented by the abstract class ImageProcessingFilter
(for more information please see: How Piczard Works )

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:

  1. By creating a totally custom filter that inherits directly from ImageProcessingFilter.
    For more information: Create a totally custom filter
  2. By inheriting from an existing filter (e.g. from TextWatermark or ColorMatrixFilter).
    For more information: Inherit from an existing filter
  3. By creating a custom filter that simply aggregates one or more existing filters.
    For more information: Aggregate one or more filters



2. Create a totally custom filter

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

The property Image of the ImageProcessingActionExecuteArgs class allows to get the current source image.
It is possible to set the property Image to a new value.
In this case, please note that:



3. Inherit from an existing filter

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).


4. Aggregate one or more filters

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.

As indicated in the previous paragraph (Create a totally custom filter), the Apply method must be added, however you don't need to write any code inside it.


An aggregate filter Copy Code
public class MyAggretatedFilters
   : ImageProcessingFilter
public 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)



5. How to use a custom filter

Once you have developed a custom filter, you can use it exactly in the same way you use the other existing Piczard filters.

Fof example you can process an image by directly invoking the SaveProcessedImageToFileSystem.
Or you can add your filter to a ImageProcessingJob so you can apply multiple filters.


Copy Code
new MyAggretatedFilters().SaveProcessedImageToFileSystem("Source.png", "Output.jpg");



6. Information for filter authors about color filters

ColorMatrixFilter It's an inheritable class (both the ImageAdjustmentsFilter class and the DefaultColorFilters class inherit from it)

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.



7. Information for filter authors about the image background color

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:

  1. 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.
  2. 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))


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.


©2013 Sergio Turolla. All Rights Reserved.