Image Wyam.Images

This module manipulates images by applying a variety of operations.

This module manipulates images by applying operations such as resizing, darken/lighten, etc. This image module does not modify your original images in any way. It will create a copy of your images and produce images in the same image format as the original. It relies on other modules such as ReadFiles to read the actual images as input and WriteFiles to write images to disk. 

Pipelines.Add("Images",
  ReadFiles("*")
    .Where(x => new[] { ".jpg", ".jpeg", ".gif", ".png"}.Contains(x.Path.Extension)),
  Image()
    .SetJpegQuality(100).Resize(400,209).SetSuffix("-thumb"),
  WriteFiles("*")
);

It will produce image with similar file name as the original image with addition of suffix indicating operations that have performed, e.g. "hello-world.jpg" can result in "hello-world-w100.jpg". The module allows you to perform more than one set of processing instructions by using the fluent property And. 

Pipelines.Add("Images",
  ReadFiles("*")
    .Where(x => new[] { ".jpg", ".jpeg", ".gif", ".png"}.Contains(x.Path.Extension)),
  Image()
    .SetJpegQuality(100).Resize(400, 209).SetSuffix("-thumb")
    .And()
    .SetJpegQuality(70).Resize(400*2, 209*2).SetSuffix("-medium"),
  WriteFiles("*")
);

The above configuration produces two set of new images, one with a "-thumb" suffix and the other with a "-medium" suffix.

Package

This module exists in the Wyam.Images package which is not part of the core distribution. Add the following preprocessor directive to your configuration file to use it:
#n Wyam.Images

Usage

  • Image()

    Process images in the content of the input document.

Fluent Methods

Chain these methods together after the constructor to modify behavior.

  • And()

    Mark the beginning of another set of processing instructions to be applied to the images.

  • BlackWhite()

    Applies black and white toning to the image.

  • Brightness(float amount)

    Brightens the image.

    • amount

      The proportion of the conversion. Must be greater than or equal to 0. A value of 0 will create an image that is completely black. A value of 1 leaves the input unchanged. Other values are linear multipliers on the effect. Values of an amount over 1 are allowed.

  • Contrast(float amount)

    Adjusts the contrast of the image.

    • amount

      A value of 0 will create an image that is completely gray. A value of 1 leaves the input unchanged. Other values are linear multipliers on the effect. Values of an amount over 1 are allowed, providing results with more contrast.

  • Hue(float degrees)

    Sets the hue of the image using 0 to 360 degree values.

    • degrees

      The degrees to set.

  • Opacity(float amount)

    Multiplies the alpha component of the image.

    • amount

      The proportion of the conversion. Must be between 0 and 1.

  • Operation(Func<IImageProcessingContext, IImageProcessingContext> operation, Func<FilePath, FilePath> pathModifier = null)

    Allows you to specify your own ImageSharp operation.

    • operation

      The operation to perform on the image.

    • pathModifier

      Modifies the destination path after applying the operation.

  • OutputAs(Action<Image, Stream> action, Func<FilePath, FilePath> pathModifier = null)

    Allows you to specify an alternate output format for the image. For example, you might use this if you want to full specify the encoder and it's properties. This will override the default behavior of outputting the image as the same format.

    • action

      An action that should write the provided image to the provided stream.

    • pathModifier

      Modifies the destination path after applying the operation (for example, to set the extension).

  • OutputAsBmp()

    Outputs the image as BMP. This will override the default behavior of outputting the image as the same format.

  • OutputAsGif()

    Outputs the image as GIF. This will override the default behavior of outputting the image as the same format.

  • OutputAsJpeg()

    Outputs the image as JPEG. This will override the default behavior of outputting the image as the same format.

  • OutputAsPng()

    Outputs the image as PNG. This will override the default behavior of outputting the image as the same format.

  • Resize(Nullable<int> width, Nullable<int> height, AnchorPositionMode anchor = 0, ResizeMode mode = 2)

    Resizes the image to a certain width and height. No resizing will be performed if both width and height are set to null.

    • width

      The desired width. If set to null or 0, the image will maintain it's original aspect ratio.

    • height

      The desired height. If set to null or 0, the image will maintain it's original aspect ratio.

    • anchor

      The anchor position to use (if necessary).

    • mode

      The resize mode to use.

  • Saturate(float amount)

    Saturates the image.

    • amount

      A value of 0 is completely un-saturated. A value of 1 leaves the input unchanged. Other values are linear multipliers on the effect. Values of amount over 1 are allowed, providing super-saturated results.

  • SetPrefix(string prefix)

    Set the prefix of the generated image, e.g. SetPrefix("medium-") will transform original filename "hello-world.jpg" to "medium-hello-world.jpg".

    • prefix

      The prefix to use.

  • SetSuffix(string suffix)

    Set the suffix of the generated image, e.g. SetSuffix("-medium") will transform original filename "hello-world.jpg" to "hello-world-medium.jpg".

    • suffix

      The suffix to use.

  • Vignette(Rgba32 color)

    Apply vignette processing to the image with specific color, e.g. Vignette(Rgba32.AliceBlue).

    • color

      The color to use for the vignette.

Input Metadata

The metadata values listed below apply to individual documents and are typically set from front matter (with just the name of the key) and used as inputs to the module to control behavior.

  • Keys.RelativeFilePath: Wyam.Common.IO.FilePath

    The path to the file relative to the input folder. This metadata value is used when generating links to the document.

Output Metadata

The metadata values listed below apply to individual documents and are created and set by the module as indicated in their descriptions.

  • Keys.WritePath: Wyam.Common.IO.FilePath

    The path to use when writing the file.

GitHub