diff --git a/doc/docfx.json b/doc/docfx.json new file mode 100644 index 00000000..830211ec --- /dev/null +++ b/doc/docfx.json @@ -0,0 +1,45 @@ +{ + "metadata": [ + { + "src": [ + { + "src": "../", + "files": [ + "out/bin/MagicScaler/Dist/**\/PhotoSauce.MagicScaler.dll" + ] + } + ], + "dest": "../out/doc/api", + "properties": { + "TargetFramework": "netcoreapp3.0", + "Configuration": "Dist" + } + } + ], + "build": { + "content": [ + { + "src": "../out/doc", + "files": "api/**.yml" + }, + { + "files": [ + "toc.yml", + "*.md" + ] + } + ], + "template": [ "default", "template" ], + "dest": "../out/doc/_site", + "intermediateFolder": "../out/obj/DocFX", + "markdownEngineName": "markdig", + "postProcessors": "ExtractSearchIndex", + "globalMetadata": { + "_appFooter": "Copyright © 2020 Clinton Ingram
Generated with DocFX", + "_appTitle": "PhotoSauce Documentation", + "_enableSearch": true, + "_enableNewTab": false, + "_gitUrlPattern": "github" + } + } +} \ No newline at end of file diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 00000000..0f05f53b --- /dev/null +++ b/doc/index.md @@ -0,0 +1,3 @@ +## Welcome to the PhotoSauce documentation site! + +The [MagicScaler API](/api/PhotoSauce.MagicScaler.html) and [WebRSize Configuration Guide](/web.html) are here, and there is more to come. \ No newline at end of file diff --git a/doc/main.md b/doc/main.md index f937fcbf..5bb4ae7f 100644 --- a/doc/main.md +++ b/doc/main.md @@ -1,565 +1 @@ -## MagicImageProcessor - -The main MagicScaler image processor. - -### EnablePlanarPipeline: static bool - -Enables MagicImageProcessor's planar format pipeline for images stored in planar ([YCbCr](https://en.wikipedia.org/wiki/YCbCr)) format. This pipeline offers significant performance advantages over standard RGB processing for JPEG images. - -Most image processing software will convert YCbCr JPEG input to RGB for processing and then convert back to YCbCr for JPEG output. In addition to saving the processing time spent on this unnecessary conversion, planar processing allows for other work savings. - -* [Chroma subsampled](https://en.wikipedia.org/wiki/Chroma_subsampling) images do not need to have their chroma planes upsampled to the luma size, only to have them rescaled again. MagicScaler can scale the subsampled chroma plane directly to its final size. -* When saving in a chroma subsampled format, the final chroma scaling is done with a high-quality resampler rather than the default resampler used by the encoder. -* When processing in [linear light](http://www.ericbrasseur.org/gamma.html), gamma correction needs only be performed on the luma plane. -* When sharpening is applied, it also needs only be performed on the luma plane. - -This feature is only available if WIC supports it (Windows 8.1/Windows Server 2012 and above) and the input image format is YCbCr. The output results will be slightly different than those produced with RGB processing but no less correct or visually appealing. - -Default Value: true - -### EnableSimd : static bool - -Enables [SIMD](https://en.wikipedia.org/wiki/SIMD) versions of many of MagicScaler's algorithms. For high-quality resampling, SIMD processing yields significant performance improvements. - -Note that the SIMD processing is done in floating point whereas the standard processing is done in fixed point math. This will result in very slight output differences due to rounding. Differences will not be visually significant but can be detected with a binary compare. - -This property should only be used for testing/troubleshooting. Forcing floating point processing on incompatible hardware or runtimes will result in very poor performance, and disabling it when supported will sacrifice much of MagicScaler's current and future optimization. - -Default Value: true if the runtime/JIT and hardware support hardware-accelerated System.Numerics.Vectors, otherwise false - -### ProcessImage(string, Stream, ProcessImageSettings) - -Accepts a file path for the input image, a stream for the output image, and a [ProcessImageSettings](#processimagesettings) object for settings. The output stream must allow Seek and Write. Returns a [ProcessImageResult](#processimageresult). - -### ProcessImage(ReadOnlySpan<byte>, Stream, ProcessImageSettings) - -Accepts a ReadOnlySpan for the input image, a stream for the output image, and a [ProcessImageSettings](#processimagesettings) object for settings. The output stream must allow Seek and Write. Returns a [ProcessImageResult](#processimageresult). - -### ProcessImage(Stream, Stream, ProcessImageSettings) - -Accepts a stream for the input image, a stream for the output image, and a [ProcessImageSettings](#processimagesettings) object for settings. The output stream must allow Seek and Write. The input stream must allow Seek and Read. Returns a [ProcessImageResult](#processimageresult). - -### ProcessImage(IPixelSource, Stream, ProcessImageSettings) - -Accepts an [IPixelSource](#ipixelsource) input, a stream for the output image, and a [ProcessImageSettings](#processimagesettings) object for settings. The output stream must allow Seek and Write. Returns a [ProcessImageResult](#processimageresult). - -### BuildPipeline(string, ProcessImageSettings) - -Accepts a file path for the input image and a [ProcessImageSettings](#processimagesettings) object for settings. Returns a [ProcessingPipeline](#processingpipeline) for custom processing. - -### BuildPipeline(ReadOnlySpan<byte>, ProcessImageSettings) - -Accepts a ReadOnlySpan for the input image and a [ProcessImageSettings](#processimagesettings) object for settings. Returns a [ProcessingPipeline](#processingpipeline) for custom processing. - -### BuildPipeline(Stream, ProcessImageSettings) - -Accepts a stream for the input image and a [ProcessImageSettings](#processimagesettings) object for settings. Returns a [ProcessingPipeline](#processingpipeline) for custom processing. The input stream must allow Seek and Read. - -### BuildPipeline(IPixelSource, ProcessImageSettings) - -Accepts an [IPixelSource](#ipixelsource) input and a [ProcessImageSettings](#processimagesettings) object for settings. Returns a [ProcessingPipeline](#processingpipeline) for custom processing. - -### ExecutePipeline(ProcessingPipeline, Stream) - -Accepts a [ProcessingPipeline](#processingpipeline) and a stream for the output image. This method completes pipeline processing by requesting the processed pixels and saving the output. The output stream must allow Seek and Read. Returns a [ProcessImageResult](#processimageresult). - -## GdiImageProcessor - -This class is included only for testing/benchmarking purposes. It will be removed in a future version and should not be used for production code. - -This class is not included in the .NET Core version. - -## WicImageProcessor - -This class is included only for testing/benchmarking purposes. It will be removed in a future version and should not be used for production code. - -## ProcessImageSettings - -Settings for the ProcessImage operation - -### Calculate(ProcessImageSettings, ImageFileInfo) - -Given a settings instance and an image, will calculate the final settings to be used, including any default or auto calculated properties. - -### FrameIndex: int - -The frame number (starting from 0) to read from a multi-frame file, such as a multi-page TIFF or animated GIF. For single-frame images, 0 is the only valid value. - -Default Value: 0 - -### Width: int - -The output image width in pixels. If auto-cropping is enabled, a value of 0 will set the width automatically based on the output height. If Width and Height are both set to 0, no resizing will be performed but a crop may still be applied. - -Default Value: 0 - -### Height: int - -The output image height in pixels. If auto-cropping is enabled, a value of 0 will set the height automatically based on the output width. If Width and Height are both set to 0, no resizing will be performed but a crop may still be applied. - -Default Value: 0 - -### DpiX: double - -The output image horizontal DPI. A value of 0 will preserve the DPI of the input image. Not all image formats support a DPI setting and most applications will ignore it. - -Default Value: 96 - -### DpiY: double - -The output image vertical DPI. A value of 0 will preserve the DPI of the input image. Not all output formats support a DPI setting and most applications will ignore it. - -Default Value: 96 - -### Sharpen: bool - -Indicates whether an [unsharp mask](https://en.wikipedia.org/wiki/Unsharp_masking) operation should be performed on the image following the resize. The sharpening settings are controlled by the [UnsharpMask](#unsharpmask-unsharpmasksettings) property. - -Default value: true - -### ResizeMode: CropScaleMode - -A [CropScaleMode](#cropscalemode) value indicating whether auto-cropping should be performed or whether the resized image may have a different aspect ratio. Auto-cropping is performed only if a [Crop](#crop-rectangle) value is not explicitly set. - -Default value: Crop - -### Crop: Rectangle - -A System.Drawing.Rectangle that specifies which part of the input image should be included. If the rectangle is empty and the [ResizeMode](#resizemode-cropscalemode) is set to `Crop`, the image will be cropped automatically. Points given for this rectangle must be expressed in terms of the input image. - -If the input image has an [Exif Orientation](http://sylvana.net/jpegcrop/exif_orientation.html) tag, rotation and/or flipping will be applied to the image before the crop. Crop values should be expressed in terms of the image's correct orientation, not the encoded orientation. - -Default value: Rectangle.Empty - -### Anchor: CropAnchor - -A [CropAnchor](#cropanchor) value indicating the position of the auto-crop rectangle. Values may be combined to specify a vertical and horizontal position. Ex: `myCrop = CropAnchor.Top | CropAnchor.Left`. - -Default value: CropAnchor.Center - -### SaveFormat: FileFormat - -A [FileFormat](#fileformat) value indicating the codec used for the output image. A value of `Auto` will choose the output codec based on the input image type. - -Default value: FileFormat.Auto - -### MatteColor: Color - -A System.Drawing.Color value indicating a background color to be applied when processing an input image with transparency. When converting to a file format that does not support transparency (e.g. PNG->JPEG), the background color will be Black unless otherwise specified. When saving as a file format that does support transparency, the transparency will be maintained unless a color is set. - -Default value: Color.Empty - -### HybridMode: HybridScaleMode - -A [HybridScaleMode](#hybridscalemode) value indicating whether hybrid processing is allowed. Hybrid processing may use the image decoder or another low-quality scaler to shrink an image to an intermediate size before the selected high-quality algorithm is applied to the final resize. This can result in dramatic performance improvements but with a reduction in image quality. - -Default value: HybridScaleMode.FavorQuality - -### BlendingMode: GammaMode - -A [GammaMode](#gammamode) value indicating whether the scaling algorithm is applied in linear or gamma-corrected colorspace. Linear processing will yield better quality in almost all cases but with a performance cost. - -Default value: GammaMode.Linear - -### MetadataNames: IEnumerable<string> - -A list of metadata policy names or explicit metadata paths to be copied from the input image to the output image. This can be useful for preserving author or copyright EXIF tags in the output image. See the [Windows Photo Metadata Policies](https://msdn.microsoft.com/en-us/library/windows/desktop/ee872003(v=vs.85).aspx) for examples of commonly-used values, or the [Metadata Query Language Overview](https://msdn.microsoft.com/en-us/library/windows/desktop/ee872003(v=vs.85).aspx) for explicit path syntax. - -Default value: null - -### JpegQuality: int - -Sets the quality value passed to the JPEG encoder for the output image. If this value is set to 0, the quality level will be set automatically according to the output image dimensions. Typically, this value should be 80 or greater if set explicitly. - -Default value: 0 - -### JpegSubsampleMode: ChromaSubsampleMode - -A [ChromaSubsampleMode](#chromasubsamplemode) value indicating how [chroma subsampling](https://en.wikipedia.org/wiki/Chroma_subsampling) is configured in the JPEG encoder for the output image. If this value is set to `Default`, the chroma subsampling will be set automatically based on the [JpegQuality](#jpegquality-int) setting. - -Default value: ChromaSubsampleMode.Default - -### Interpolation: InterpolationSettings - -An [InterpolationSettings](#interpolationsettings) object specifying details of the sampling algorithm to use for image scaling. If this value is unset, the algorithm will be chosen automatically based on the ratio of input image size to output image size. - -Default value: unset - -### UnsharpMask: UnsharpMaskSettings - -An [UnsharpMaskSettings](#unsharpmasksettings) object specifying sharpening settings. If this value is unset, the settings will be chosen automatically based on the ratio of input image size to output image size. - -Default value: unset - -### ColorProfileMode : ColorProfileMode - -A [ColorProfileMode](#colorprofilemode) value indicating how embedded [ICC Color Profiles](https://en.wikipedia.org/wiki/ICC_profile) are handled during processing. - -Default value: Normalize - -### OrientationMode : OrientationMode - -An [OrientationMode](#orientationmode) value indicating how [Exif Orientation](https://magnushoff.com/jpeg-orientation.html) correction is handled during processing. - -Default value: Normalize - -## CropAnchor - -A flags enumeration for specifying auto-crop anchor. - -By default, auto-cropping will maintain the image center by cropping equally from the top, bottom, or sides. If you wish to direct the auto-cropper to focus on another part of the image, you may specify a vertical and horizontal bias using a combination of values. Only one horizontal and one vertical value may be combined. - -* Center -* Top -* Bottom -* Left -* Right - -## CropScaleMode - -An enumeration for specifying auto-crop or auto-size behavior. - -### Crop - -Auto-crop the input image to fit within the given Width and Height while maintaining the aspect ratio of the input image. - -### Max - -Auto-size the output image to a maximum of the values given for Width and Height while maintaining aspect ratio of the input image. - -### Stretch - -Allow the output image Width and Height to change the aspect ratio of the input image. This may result in stretching or distortion of the image. - -### Pad - -Maintain the image aspect ratio of the input image, but fill the given Width and Height. Borders will be added if necessary and filled with the `MatteColor`. - -### Examples - -Suppose you have an input image with dimensions of 640x480 and you set the Width and Height of the output image to 100x100. -`Crop` will produce an output image of 100x100, preserving the aspect ratio of the input image by cropping from the sides of the image. By default, this will crop evenly from the left and right. You can change that behavior by changing the [Anchor](#anchor-cropanchor) value. -`Max` will produce an output image of 100x75, preserving the aspect ratio of the input image by constraining the dimensions of the output image. -`Stretch` will produce an output image of 100x100 that is squished horizontally. -`Pad` will produce an output image of 100x100, with top and bottom borders surrounding the resized input. - -When using `Crop` mode, you may also choose to specify only one of the Width or Height. In this case, the undefined dimension will be set automatically to preserve the source image's aspect ratio after taking the Crop setting into account. -Again, using a 640x480 input image as an example, you can expect the following: - -Width=100 with the default values Height=0/Crop=Rectangle.Empty will result in an output image of 100x75 with no cropping. -Height=100 with the default values Width=0/Crop=Rectangle.Empty will result in an output image of 133x100 with no cropping. -Width=100/Crop=Rectangle.FromLTRB(0,0,480,480) with the default value Height=0 will result in an output image of 100x100 with the right portion of the image cropped. You can achieve the same result with Width=100/Height=100/Anchor=CropAnchor.Left. - -## HybridScaleMode - -An enumeration for specifying the amount of low-quality scaling performed in high-ratio resizing operations. - -### FavorQuality - -Resize the image to an intermediate size at least 3x the output dimensions with the low-quality scaler. Perform the final resize with the high-quality scaler. - -### FavorSpeed - -Resize the image to an intermediate size at least 2x the output dimensions with the low-quality scaler. Perform the final resize with the high-quality scaler. - -### Turbo - -Resize the image entirely using the low-quality scaler if possible. If not possible, perform the minimal amount of work possible in the high-quality scaler. - -### Off - -Perform the entire resize with the high-quality scaler. This will yield the best quality image but at a performance cost. - -## GammaMode - -An enumeration for specifying the light blending mode used for high-quality scaling operations. - -### Linear - -Convert values to linear RGB before blending. This is more [mathematically correct](http://blog.johnnovak.net/2016/09/21/what-every-coder-should-know-about-gamma/) and more visually pleasing in most cases. - -### Companded - -Blend companded R'G'B' values directly. This is usually a poor choice but may be used for compatibility with other software or where speed is more important than image quality. - -## ChromaSubsampleMode - -An enumeration for specifying the [chroma subsampling](https://en.wikipedia.org/wiki/Chroma_subsampling) mode used by the JPEG encoder. - -### Default - -Choose the chroma subsampling mode automatically based on the JpegQuality setting - -### Subsample420 - -4:2:0 chroma subsampling - -### Subsample422 - -4:2:2 chroma subsampling - -### Subsample444 - -No chroma subsampling (4:4:4) - -## FileFormat - -An enumeration for specifying the file format (codec) used for the output image. - -### Auto - -Choose the output file format automatically based on the format of the input image - -### Jpeg - -JPEG. Use JpegQuality and JpegSubsampleMode settings to control output. - -### Png - -24-bit or 32-bit PNG, depending on whether or not the input image contains an alpha channel. - -### Png8 - -8-bit indexed PNG - -### Gif - -8-bit indexed GIF - -### Bmp - -24-bit or 32-bit BMP, depending on whether or not the input image contains an alpha channel. - -### Tiff - -Uncompressed 24-bit or 32-bit TIFF, depending on whether or not the input image contains an alpha channel. - -## ColorProfileMode - -An enumeration for indicating how embedded [ICC Color Profiles](https://en.wikipedia.org/wiki/ICC_profile) are handled. - -### Normalize - -Convert the input image to the [sRGB color space](https://en.wikipedia.org/wiki/SRGB) during processing. Output an untagged sRGB image. - -### NormalizeAndEmbed - -Convert the input image to the sRGB color space during processing. Embed a [compact sRGB profile](https://github.com/saucecontrol/Compact-ICC-Profiles) in the output. This option ensures maximum compatibility with web browsers and other software but results in slightly larger (+456 bytes) output files. - -### Preserve - -Preserve the input image color space during processing. Embed the ICC profile in the output image. If the output format does not support embedded profiles, it will be discarded. Use this option only if the output format and viewing software support color management. - -### Ignore - -Ignore any embedded profiles and treat the image as sRGB data. Do not tag the output image. This option may result in significant changes to output color and should only be used if the embedded profile is known to be incorrect. - -## OrientationMode - -An enumeration for indicating how [Exif Orientation](https://magnushoff.com/jpeg-orientation.html) is handled. - -### Normalize - -Correct the image orientation according to the Exif tag on load. Save the output in normal orientation. This option ensures maximum compatibility with viewer software. - -### Preserve - -Preserve the orientation of the input image and tag the output image to reflect the orientation. If the output format does not support orientation tagging, it will be discarded. Use this option only if the output format and viewing software support orientation correction. - -### Ignore - -Ignore any orientation tag and treat the image as if its stored orientation is normal. Do not tag the output image. This option should only be used if the Exif orientation of the input image is known to be incorrect. - -## UnsharpMaskSettings - -A structure for specifying the settings used for the post-resize [sharpening](https://en.wikipedia.org/wiki/Unsharp_masking) of the output image. These settings are designed to function similarly to the Unsharp Mask settings in Photoshop. - -### Amount: int - -The amount of sharpening applied. Technically, this is a percentage applied to the luma difference between the original and blurred images. Typical values are between 25 and 200. - -### Radius: double - -The radius of the gaussian blur used for the unsharp mask. More blurring in the mask yields more sharpening in the final image. Typical values are between 0.3 and 3.0. Larger radius values can have significant performance cost. - -### Threshold - -The minimum difference between the original and blurred images for a pixel to be sharpened. When using larger `Radius` or `Amount` values, a larger `Threshold` value can ensure lines are sharpened while textures are not. Typical values are between 0 and 10. - -## InterpolationSettings - -A structure for specifying the sampling algorithm used by the high-quality scaler. There are a number of well-known algorithms preconfigured as static fields, or you can define your own. - -Preconfigured values include: - -* [NearestNeighbor](http://www.imagemagick.org/Usage/filter/#point) - AKA Point -* [Average](http://www.imagemagick.org/Usage/filter/#box) - AKA Box -* [Linear](http://www.imagemagick.org/Usage/filter/#triangle) - AKA Bilinear/Triangle/Tent -* [Quadratic](http://neildodgson.com/pubs/quad.pdf) - A slightly faster alternative to Catmull-Rom with similar output but a greater chance of artifacts -* [Hermite](http://www.imagemagick.org/Usage/filter/#hermite) - A Cubic filter with B=0, C=0 - Similar to Linear but with slightly smoother output -* [Mitchell](http://www.imagemagick.org/Usage/filter/#mitchell) - AKA Mitchell-Netravali - A Cubic filter with B=1/3, C=1/3 -* [CatmullRom](http://www.imagemagick.org/Usage/filter/#catrom-c) - AKA Catrom - A Cubic filter with B=0, C=0.5 -* [Cubic](http://www.imagemagick.org/Usage/filter/#cubics) - A Cubic filter with B=0, C=1 - Similar to GDI+'s HighQualityBicubic for high-ratio downscaling -* CubicSmoother - A Cubic filter with B=0, C=0.625 and Blur=1.15 - Similar to Photoshop's Bicubic Smoother and GDI+'s HighQualityBicubic when enlarging -* [Lanczos](http://www.imagemagick.org/Usage/filter/#lanczos) - A 3-lobed Lanczos Windowed Sinc filter -* [Spline36](http://www.panotools.org/dersch/interpolator/interpolator.html) - A 3-lobed piece-wise function with a nice balance between smoothness and sharpness - -### WeightingFunction: IInterpolator - -A reference to an object implementing IInterpolator, which specifies the sampling range for the filter and a function to generate the weighting value for a given distance. - -### Blur: double - -A value used to stretch (or compress) the sampling range for the filter. The default and recommended value is 1. You may use a value greater than 1 to blur or smooth the sampling function. Values less than 1 can cause unpleasant artifacts. - -## IInterpolator - -An interface for defining custom sampling functions. - -### Support: double - -The support radius of the sampling function. The sampling window will be twice this value. - -### GetValue(double) returns double - -The weighting function. This function accepts a distance from the destination sample's center and returns a weight for the sample at that distance. - -## ProcessImageResult - -This class encapsulates information about the results of an image processing operation. It includes the settings used for the processing as well as some basic instrumentation. - -### Settings: ProcessImageSettings - -The settings used for the processing operation. If any settings supplied in the input were set to automatic values, this object will reflect the calculated values used. - -### Stats: IEnumerable<PixelSourceStats> - -A collection of [PixelSourceStats](#pixelsourcestats) objects containing information about the number of pixels processed and time taken in each stage of the pipeline. - -## PixelSourceStats - -This class encapsulates basic instrumentation for the [IPixelSource](#ipixelsource) used in each stage of the processing pipeline. - -### CallCount: int - -The number of times CopyPixels() was called on this pixel source. - -### PixelCount: int - -The total number of pixels requested from the pixel source. - -### ProcessingTime: double - -The total processing time (in milliseconds) for this pixel source. Some WIC wrappers may report times that include the processing of chained pixel sources they use and may not, therefore report times accurately. This information is most useful for diagnosing performance issues in your own pixel sources or transforms. - -### SourceName: string - -The name of the pixel source as returned by ToString(). The default ToString() implementation returns the class name, but this may be overridden, so the output may not make sense. - -## IPixelSource - -This interface defines a custom pixel source. It can either retrieve those pixels from an upstream source or can generate them itself. For a sample implementation, refer to the [TestPatternPixelSource](../src/MagicScaler/Magic/TestPatternPixelSource.cs) code. - -### Width: int - -The width of the source image in pixels. - -### Height: int - -The height of the source image in pixels. - -### Format: Guid - -The [WIC pixel format](https://msdn.microsoft.com/en-us/library/windows/desktop/ee719797.aspx) GUID of the source image. For the current version, this must be a value included as one of the [PixelFormats](#pixelformats) static fields. - -### CopyPixels(Rectangle, long, long, IntPtr) - -Copy pixels from the source image. The caller will provide a rectangle specifying an area of interest and an IntPtr that points to a destination byte buffer as well as a stride and buffer length. If writing a custom IPixelSource, it is your responsibility to implement this method to provide pixels to downstream sources and transforms. - -## PixelFormats - -This static class contains member fields for each of the supported WIC pixel format GUIDs. - -### Bgr24bpp - -24 bits-per-pixel. 8 bits-per-channel in BGR channel order. - -### Bgra32bpp - -32 bits-per-pixel. 8 bits-per-channel in BGR channel order, plus an 8-bit alpha channel. - -### Grey8bpp - -8 bits-per-pixel greyscale. - -## IPixelTransform : IPixelSource - -This interface inherits from [IPixelSource](#ipixelsource) and is intended to be used to build a custom processing step. For a sample implementation, refer to the [ColorMatrixTransform](../src/MagicScaler/Magic/ColorMatrixTransform.cs) code. - -### Init(IPixelSource) - -The pipeline will call this method and pass in the upstream pixel source. Use this method to configure the transform according to its own settings and the properties of the upstream source. - -## ProcessingPipeline - -This class represents an image processing pipeline that is configured but not yet executed. This allows for further customization of the processing, such as filtering, before the pipeline is executed and the output image saved. It also allows pixels to be pulled from the pipeline rather than written directly to an output image. - -### PixelSource: IPixelSource - -The [IPixelSource](#ipixelsource) representing the current last step of the pipeline. The image properties and CopyPixels() results reflect all processing that has been configured up to the current point in the pipeline. - -### Settings: ProcessImageSettings - -The [ProcessImageSettings](#processimagesettings) object representing the current state of the settings on this pipeline. Any settings configured with automatic values initially will have their calculated values at this point. - -### Stats: IEnumerable<PixelSourceStats> - -A collection of the [PixelSourceStats](#pixelsourcestats) for all processing up to this point. Until CopyPixels() is called on the PixelSource, there will be no stats to report. - -### AddTransform(IPixelTransform) - -Adds an [IPixelTransform](#ipixeltransform) to the pipeline. This allows for custom filtering of the pipeline output before the final image is saved. - -### ExecutePipeline(Stream) - -This extension method on the [MagicImageProcessor](#magicimageprocessor) requests all pixels from the pipeline and saves the output to a stream. You may use this after configuring the pipeline (e.g. adding filters) if you do not wish to request the pixels from the PixelSource. - -## ImageFileInfo - -This class reads and exposes basic information about an image file from its header. - -### ContainerType: FileFormat - -The [FileFormat](#fileformat) of the image. This is based on the contents of the image, not its file name/extension. - -### FileDate: DateTime - -The last modified date of the image file, if available. - -### FileSize: int - -The size of the image file, in bytes, if available. - -### Frames: FrameInfo[] - -An array of [FrameInfo](#frameinfo) objects, with details about each image frame in the file. - -## FrameInfo - -This class describes a single image frame from within an image file. All valid images have at least one frame, some (e.g. TIFF and GIF) may have many. - -### Width: int - -The width of the image frame in pixels. - -### Height: int - -The height of the image frame in pixels. - -### HasAlpha: bool - -True if the image frame has a separate alpha channel or if it is in an indexed format and any of the color values have a transparency value set. - -### ExifOrientation: Orientation - -The [Exif Orientation](https://magnushoff.com/jpeg-orientation.html) value stored for this image frame. The Width and Height values are pre-corrected according to this value, so you can ignore it if you are using MagicScaler to process the image, as it performs orientation correction automatically. The integer values defined in the Orientation enumeration match the stored Exif values. +This documentation has moved. Please refer to the new DocFX site. diff --git a/doc/template/partials/head.tmpl.partial b/doc/template/partials/head.tmpl.partial new file mode 100644 index 00000000..c05e8c1b --- /dev/null +++ b/doc/template/partials/head.tmpl.partial @@ -0,0 +1,21 @@ +{{!Copyright (c) Oscar Vasquez. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}} + + + + + {{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}} + + + + {{#_description}}{{/_description}} + + + + + + + + {{#_noindex}}{{/_noindex}} + {{#_enableSearch}}{{/_enableSearch}} + {{#_enableNewTab}}{{/_enableNewTab}} + \ No newline at end of file diff --git a/doc/template/styles/main.css b/doc/template/styles/main.css new file mode 100644 index 00000000..ea3538be --- /dev/null +++ b/doc/template/styles/main.css @@ -0,0 +1,280 @@ +/* COLOR VARIABLES*/ +:root { + --primary-color: #0d47a1; + --primary-light: #5e92f3; + --primary-dark: #003c8f; + --font-color: #34393e; +} + +body { + color: var(--font-color); + font-family: "Roboto", sans-serif; + line-height: 1.5; + font-size: 16px; + -ms-text-size-adjust: 100%; + -webkit-text-size-adjust: 100%; + word-wrap: break-word; +} + +/* HIGHLIGHT COLOR */ + +button, +a { + color: var(--primary-dark); + cursor: pointer; +} + +button:hover, +button:focus, +a:hover, +a:focus { + color: var(--primary-light); + text-decoration: none; +} + +.toc .nav > li.active > a { + color: var(--primary-dark); +} + +.toc .nav > li.active > a:hover, +.toc .nav > li.active > a:focus { + color: var(--primary-light); +} + +.pagination > .active > a { + background-color: var(--primary-color); + border-color: var(--primary-color); +} + +.pagination > .active > a, +.pagination > .active > a:focus, +.pagination > .active > a:hover, +.pagination > .active > span, +.pagination > .active > span:focus, +.pagination > .active > span:hover { + background-color: var(--primary-light); + border-color: var(--primary-light); +} + +/* HEADINGS */ + +h1 { + font-weight: 600; + font-size: 32px; +} + +h2 { + font-weight: 600; + font-size: 24px; + line-height: 1.8; +} + +h3 { + font-weight: 600; + font-size: 20px; + line-height: 1.8; +} + +h5 { + font-size: 14px; + padding: 10px 0px; +} + +article h1, +article h2, +article h3, +article h4 { + margin-top: 35px; + margin-bottom: 15px; +} + +article h4 { + padding-bottom: 8px; + border-bottom: 2px solid #ddd; +} + +/* NAVBAR */ + +.navbar-brand > img { + color: #fff; +} + +.navbar { + border: none; + /* Both navbars use box-shadow */ + -webkit-box-shadow: 0px 1px 3px 0px rgba(100, 100, 100, 0.5); + -moz-box-shadow: 0px 1px 3px 0px rgba(100, 100, 100, 0.5); + box-shadow: 0px 1px 3px 0px rgba(100, 100, 100, 0.5); +} + +.subnav { + border-top: 1px solid #ddd; + background-color: #fff; +} + +.navbar-inverse { + background-color: var(--primary-color); + z-index: 100; +} + +.navbar-inverse .navbar-nav > li > a, +.navbar-inverse .navbar-text { + color: #fff; + background-color: var(--primary-color); + border-bottom: 3px solid transparent; + padding-bottom: 12px; +} + +.navbar-inverse .navbar-nav > li > a:focus, +.navbar-inverse .navbar-nav > li > a:hover { + color: #fff; + background-color: var(--primary-color); + border-bottom: 3px solid white; +} + +.navbar-inverse .navbar-nav > .active > a, +.navbar-inverse .navbar-nav > .active > a:focus, +.navbar-inverse .navbar-nav > .active > a:hover { + color: #fff; + background-color: var(--primary-color); + border-bottom: 3px solid white; +} + +.navbar-form .form-control { + border: none; + border-radius: 20px; +} + +/* SIDEBAR */ + +.toc .level1 > li { + font-weight: 400; +} + +.toc .level2 > li { + padding: 3px; +} + +.toc .nav > li > a { + color: var(--font-color); +} + +.sidefilter { + background-color: #fff; + border-left: none; + border-right: none; +} + +.sidefilter { + background-color: #fff; + border-left: none; + border-right: none; +} + +.toc-filter { + padding: 10px; + margin: 0; +} + +.toc-filter > input { + border: 2px solid #ddd; + border-radius: 20px; +} + +.toc-filter > .filter-icon { + display: none; +} + +.toc-filter > .clear-icon { + top: 18px; + right: 18px; +} + +.sidetoc > .toc { + background-color: #fff; + overflow-x: hidden; +} + +.sidetoc { + background-color: #fff; + border: none; +} + +/* ALERTS */ + +.alert { + padding: 0px 0px 5px 0px; + color: inherit; + background-color: inherit; + border: none; + box-shadow: 0px 2px 2px 0px rgba(100, 100, 100, 0.4); +} + +.alert > p { + margin-bottom: 0; + padding: 5px 10px; +} + +.alert > ul { + margin-bottom: 0; + padding: 5px 40px; +} + +.alert > h5 { + padding: 10px 15px; + margin-top: 0; + text-transform: uppercase; + font-weight: bold; + border-radius: 4px 4px 0 0; +} + +.alert-info > h5 { + color: #1976d2; + border-bottom: 4px solid #1976d2; + background-color: #e3f2fd; +} + +.alert-warning > h5 { + color: #f57f17; + border-bottom: 4px solid #f57f17; + background-color: #fff3e0; +} + +.alert-danger > h5 { + color: #d32f2f; + border-bottom: 4px solid #d32f2f; + background-color: #ffebee; +} + +/* CODE HIGHLIGHT */ +pre { + padding: 9.5px; + margin: 1rem 0; + font-size: 13px; + word-break: break-all; + word-wrap: break-word; + background-color: #fafafe; + border-radius: 4px; + box-shadow: 0px 1px 4px 1px rgba(100, 100, 100, 0.4); +} + +.markdown span.xref { + font-family: Menlo,Monaco,Consolas,"Courier New",monospace; + font-size: 90%; + background-color: #fafafa; + padding: 2px 4px; + border-radius: 4px +} + +p + p, p + hr, p + ol, p + ul, p + .alert, pre + p { + margin-top: 2rem; +} + +.contribution > .nav > li:first-of-type { display: none; } +.pull-right.mobile-hide { display: none; } + +@media only screen and (min-width: 768px) { + .pull-right.mobile-hide + .pull-right.mobile-hide { + display: block; + } +} diff --git a/doc/toc.yml b/doc/toc.yml new file mode 100644 index 00000000..1ab51734 --- /dev/null +++ b/doc/toc.yml @@ -0,0 +1,6 @@ +- name: MagicScaler API + topicUid: PhotoSauce.MagicScaler +- name: WebRSize + href: web.md +- name: GitHub + href: https://github.com/saucecontrol/PhotoSauce diff --git a/doc/web.md b/doc/web.md index fbf376db..e6d8dcef 100644 --- a/doc/web.md +++ b/doc/web.md @@ -1,8 +1,11 @@ # WebRSize Configuration Guide -In order to reduce overhead and improve security, WebRSize requires explicit opt-in for the image folders you want processed. WebRSize will not perform any processing at all unless at least one image folder is configured. You must register a WebRSize `ConfigSection` to store this configuration. +> [!NOTE] +> WebRSize currently only works with ASP.NET hosted with IIS Integrated Pipeline Mode. A version for ASP.NET Core will be released later. -``` +In order to reduce overhead and improve security, WebRSize requires explicit opt-in for the image folders you want processed. You must register a WebRSize `ConfigSection` to store this configuration. + +```XML
@@ -10,7 +13,7 @@ In order to reduce overhead and improve security, WebRSize requires explicit opt A minimal configuration must specify the disk cache location and at least one image folder. -``` +```XML @@ -21,6 +24,11 @@ A minimal configuration must specify the disk cache location and at least one im The folder specified in the `diskCache` element must exist, and the App Pool identity must have write access to that folder. Requests matching paths specified in the `imageFolders` element are eligible for processing by WebRSize. All other requests pass through WebRSize unchanged. +> [!IMPORTANT] +> WebRSize will not perform any processing at all unless at least one image folder is configured. + +--- + Processing and caching are managed by an `IHttpModule` implementation called `WebRSizeModule`. This module examines inbound requests matching the configured image folder paths and either serves a cached already-processed image or processes the image on the fly and schedules a copy to be saved to the disk cache. The `WebRSizeModule` must receive event notifications for static image requests in your configured folders in order to do its job. There are multiple ways to accomplish this. @@ -29,7 +37,7 @@ The `WebRSizeModule` must receive event notifications for static image requests 2. You can register the module explicitly in the `system.webServer` section. - ``` + ```XML @@ -40,7 +48,7 @@ The `WebRSizeModule` must receive event notifications for static image requests 3. You can set up an explicit handler mapping for image file extension you want to process that maps to a managed `IHttpHandler`. - ``` + ```XML @@ -49,6 +57,10 @@ The `WebRSizeModule` must receive event notifications for static image requests ``` This is common in scenarios where images will be served from a `VirtualPathProvider` that uses a database or cloud storage. The built-in `StaticFileHandler` will request files from the registered `VirtualPathProvider`, and because the handler is managed, the self-registered `WebRSizeModule` instance will be able to intercept image processing requests. +  + +--- + ## Configuration Reference ### Disk Cache @@ -78,7 +90,8 @@ The pattern used is as follows: The hash is used as the first part of the file name to prevent performance issues associated with 8.3-compatible name collisions. If you have different preferences, you may create your own naming strategy by inheriting the `CacheFileNamingStrategyBase` class and implementing the abstract `GetCacheFilePath` method. Note that WebRSize uses a normalized version of the settings when creating the Settings Hash so that parameter combinations that yield the same file net results all share the same cache file. For example, imagine you have a master JPEG image that is 3000x2000 pixels. The following query string parameter sets would all generate the same image, so they would all serve the same file from the cache. -``` + +```INI w=300 h=200 w=300&h=200 @@ -88,7 +101,7 @@ w=300&format=jpg w=300&format=jpeg w=300&sharpen=true w=300&gamma=linear -... and many more +... and many, many more ``` ### Image Folders @@ -123,7 +136,7 @@ Default Value 10,000,000 The `defaultSettings` element allows you to define a collection of key/value pairs that specify settings you would like applied to all WebRSize requests in the absence of an override on the query string. For example, if you wish to disable sharpening on an entire image folder, you need not append the `sharpen=false` value to all request query strings. You can configure it as a folder default. -``` +```XML @@ -141,7 +154,7 @@ Any parameter value that would be valid on the query string of a request can be ## Query String Parameters -The following MagicScaler `ProcessImageSettings` values can be set from the query string when processing an image through a configured `ImageFolder`. See the [MagicScaler documentation](main.md) for more details. +The following MagicScaler `ProcessImageSettings` values can be set from the query string when processing an image through a configured `ImageFolder`. See the [MagicScaler documentation](/api/PhotoSauce.MagicScaler.ProcessImageSettings.html) for more details. | ProcessImageSettings
Property| QueryString
Name | QueryString
Values/Type | |---|---|---| @@ -149,6 +162,7 @@ The following MagicScaler `ProcessImageSettings` values can be set from the quer | Width | width
w | int | | Height | height
h | int | | Crop | crop | [left(int)],[top(int)],[width(int)],[height(int)] | +| CropBasis | cropbasis | [width(int)],[height(int)] | | CropAnchor | anchor | [vertical(center, top, bottom)]\|[horizontal(center, left, right)] | | ResizeMode | mode | crop, max, stretch | | Sharpen | sharpen | bool | @@ -175,7 +189,7 @@ Normally static images can be cached and served by the `http.sys` kernel cache. This sample policy ensures that any requests for .jpg files can be kernel-cached as long as the URL (including query string) matches. This will allow your processed images to be served with performance equal to that of static image files once they've been cached to disk. -``` +```XML @@ -187,7 +201,7 @@ This sample policy ensures that any requests for .jpg files can be kernel-cached You can verify kernel caching is working for processed image requests with the `netsh http show cachestate` command. The output looks something like this when items are cached: -``` +```INI PS C:\> netsh http show cachestate Snapshot of HTTP response cache: @@ -205,8 +219,6 @@ URL: http://localhost/images/test1.jpg?w=150&h=150&mode=max Content length: 21335 Hit count: 3 Force disconnect after serving: FALSE - -... ``` There are several other restrictions that affect caching, so you may not see many (or any) responses cached, even if you have a policy configured. By default, a single URL has to be requested more than twice within a 10-second window to be considered cache-worthy, and the response must be smaller than 256KB.