Module grayscale
Operations to find and operate on grayscale values.
The signed distance field operations wrap Mikko Mononen's SDF.
The Bytes type—specified below—may be any object that implements ByteReader, including strings.
For all functions, isufficient input images will be padded with 0 bytes.
(The comments that follow were adapted from sdf.h.)
Sweep-and-update Euclidean distance transform of an antialiased image for contour texturing.
The code is based on edtaa3func.c by Stefan Gustavson and improves the original in terms of memory usage and execution time.
The algorithms first traverse the image and uses gradient direction and the edge function
from edtaa3 to find an approximated point on the contour of the input image. After this pass
the distance at the edge pixels are known, and the code proceeds to update the rest of the
distance field using sweep-and-update until the distance field convergences (or max passes run).
The code procudes comparable, but probably not as accurate, distance fields as the original code.
The code is intended to be used to calculate distance fields for contour texturing.
Notice in sdf.h:
Copyright (C) 2014 Mikko Mononen (memon@inside.org)
Copyright (C) 2009-2012 Stefan Gustavson (stefan.gustavson@gmail.com)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Functions
- build_distance_field (input, radius, w, h, opts)
-
Sweep-and-update Euclidean distance transform of an antialised image for contour textures.
Based on
edtaa3func.cby Stefan Gustavson, cf. the summary above.White (255) pixels are treated as object pixels, zero pixels are treated as background. An attempt is made to treat antialiased edges correctly. The input image must have pixels in the range [0, 255], and the antialiased image should be a box-filter sampling of the ideal, crisp edge. If the antialias region is more than one pixel wide, the result from this transform will be inaccurate.
Pixels at image border are not calculated and are set to 0.
The output distance field is encoded as bytes, where 0 = radius (outside) and 255 = -radius (inside).
Input and output can be the same buffer. (Support for blobs is planned and would be exposed via opts.)
Parameters:
- input Bytes Input image, one byte per pixel.
- radius number The radius of the distance field narrow band in pixels.
- w uint Width of the image...
- h uint ...and height.
- opts
optional table
Build options, which include:
- in_stride: Bytes per row on input image (w by default)...
- out_stride: ...and on output image (again, default w).
- as_userdata: Affects how the image data is returned.
Returns:
-
Bytes
On success, the output of the distance transform, one byte per pixel.
If opts.as_userdata was true, the data is returned as a userdata that implements ByteReader, rather than being converted to a more friendly string. Under some circumstances, this might be worth doing for performance reasons.
Or
- nil, indicating an error.
- string Error message.
- coverage_to_distance_field (input, w, h, opts)
-
This function converts the antialiased image where each pixel represents coverage (box-filter
sampling of the ideal, crisp edge) to a distance field with narrow band radius of
sqrt(2).This is the fastest way to turn antialised image to contour texture. This function is good if you don't need the distance field for effects (e.g. fat outline or dropshadow).
Input and output buffers must be different.
Parameters:
- input Bytes Input image, one byte per pixel.
- w uint Width of the image...
- h uint ...and height.
- opts optional table As per build_distance_field.
Returns:
-
Bytes
As per build_distance_field.
Or
- nil, indicating an error.
- string Error message.
- rgb_to_gray (input, w, h, opts)
-
Converts a (three-bytes-per-pixel) RGB image into a grayscale one.
Parameters:
- input Bytes Input image, in RGB form.
- w uint Width of image...
- h uint ...and height.
- opts optional table As per build_distance_field, but may also contain a gray_method field, which can have as value any of the GrayscaleScheme choices, "average" being the default.
Returns:
-
Bytes
As per build_distance_field.
Or
- nil, indicating an error.
- string Error message.
- rgba_to_gray (input, w, h, opts)
-
Variant of rgb_to_gray that also considers alpha.
Parameters:
- input Bytes Input image, in RGBA form.
- w uint Width of image...
- h uint ...and height.
- opts optional table As per rgb_to_gray.
Returns:
-
Bytes
As per rgb_to_gray.
Or
- nil, indicating an error.
- string Error message.
Tables
- GrayscaleScheme
-
Various ways to compute grayscale from RGB. The "fields" are different strings that may be
assigned as gray_method for either rgb_to_gray or rgba_to_gray.
Fields:
- average Grayscale as average of r, g, and b.
- lightness
Grayscale as average of
max(r, g, b)andmin(r, g, b). - max
Grayscale from
max(r, g, b)... - min
...and
min(r, g, b). - red Interpret r as grayscale...
- green ...or g...
- blue ...or b.
- 601 YUV luminance according to Recommendation 601...
- 709 ...and Recommendation 709.