s3d.image
Functions and classes for handling image oriented data.
Module Data
alphaFunctions
A table of alpha functions potentially useful in ApplyFilter function calls. The result of an alpha function ranges from 0 to 1 indicating whether a given pixel should be processed by a filter and if so how much of the result should be mixed with any existing value.
alphaFunctions.Always (h, v, maskImage, context)
h -> integer
v -> integer
maskImage -> s3d.image.Layer
context -> integer
Returns 1 for every pixel.
alphaFunctions.MatchContext (h, v, maskImage, context)
h -> integer
v -> integer
maskImage -> s3d.image.Layer
context -> integer
Returns 1 for each pixel for which 'context' matches the pixel value at that position in 'maskImage', otherwise returns 0.
alphaFunctions.MatchNotContext (h, v, maskImage, context)
h -> integer
v -> integer
maskImage -> s3d.image.Layer
context -> integer
Returns 0 for each pixel for which 'context' matches the pixel value at that position in 'maskImage', otherwise returns 1.
filterFunctions
A table of filter functions potentially useful in ApplyFilter function calls.
filterFunctions.Blur (h, v, colorImage, currentPixel)
h -> integer
v -> integer
colorImage -> s3d.image.Layer
currentPixel -> s3d.image.RGBAFloatPixel
A 3x3 gaussian filter, providing a slight blurring effect.
filterFunctions.Median (h, v, colorImage, currentPixel)
h -> integer
v -> integer
colorImage -> s3d.image.Layer
currentPixel -> s3d.image.RGBAFloatPixel
A 3x3 median filter, useful for eliminating single pixel artifacts.
Module Functions
ApplyFilter
A general purpose layer convolution function, controllable through the required filter function and the optional alpha function and mask layer.
ApplyFilter (filterFunction, sourceLayer [, alphaFunction, maskLayer, context ])
filterFunction -> function (h, v, colorImage, currentPixel)
sourceLayer -> s3d.image.Layer
alphaFunction -> optional function (h, v, maskImage, context)
maskLayer -> optional s3d.image.Layer
context -> optional unsigned integer
The filter function is required along with the source layer, but the alpha function, mask layer and context are optional. This function will call the filter function for every pixel in the source layer for which the alpha function returns a non-zero value, or for all pixels if there is no alpha function.
CreateLayer
A general purpose layer construction function. Pass in the desired pixel type (from the kType constant data of the pixel class) and the desired size. The result is an uninitialized image layer.
CreateLayer (pixelType, width, height) -> s3d.image.Layer
pixelType -> integer
width -> integer
height -> integer
Call this function to create a layer with the given pixel type and of the given size. Both width and height must be greater than zero.
Module Classes
Buffer (derived from s3d.obj.Object)
This class has the following TransferOption constant data members:
Buffer.kErase -> integer
Buffer.kPad -> integer
Buffer.kStretch -> integer
Every instance of this class has the following member methods:
Buffer:AddLayer(Integer) -> s3d.image.Layer
Buffer:AddLayer(Integer, String) -> s3d.image.Layer
Buffer:AddLayer(Integer, String, Boolean) -> s3d.image.Layer
Buffer:AddLayer(Layer) -> boolean
Buffer:AddLayer(Layer, String) -> boolean
Buffer:AddLayer(Layer, String, Boolean) -> boolean
Buffer:BlendPixel(Number, Integer, Integer, RGBFloatPixel, Number, Number)
Buffer:BlitFrom(Buffer, Rectangle, Point)
Buffer:Clone() -> s3d.image.Buffer
Buffer:CloneAtNewSize(Point) -> s3d.image.Buffer
Buffer:CopyFrom(Buffer)
Buffer:Erase(Boolean) -> boolean
Buffer:Flip(Boolean, Boolean, Boolean) -> boolean
Buffer:GetColor(Integer, Integer) -> s3d.image.RGBFloatPixel
Buffer:GetColorLayer() -> s3d.image.Layer
Buffer:GetDPI() -> integer, integer
Buffer:GetDepth(Integer, Integer) -> integer
Buffer:GetDepthLayer() -> s3d.image.Layer
Buffer:GetIndexedLayer(Integer) -> s3d.image.Layer
Buffer:GetIndexedLayerName(Integer) -> string
Buffer:GetMaskLayer() -> s3d.image.Layer
Buffer:GetNamedLayer(String) -> s3d.image.Layer
Buffer:GetNamedLayer(String, Boolean) -> s3d.image.Layer
Buffer:GetNumberOfLayers() -> integer
Buffer:GetSize() -> s3d.vec.Point
Buffer:GetTransparency(Integer, Integer) -> integer
Buffer:HasLayer(Layer) -> boolean
Buffer:Invert(Boolean) -> boolean
Buffer:MergeFrom(Buffer, Rectangle)
Buffer:RemoveLayer(Layer)
Buffer:SetArea(Integer, Integer, Integer, Integer, RGBFloatPixel, Number, Number)
Buffer:SetArea(Rectangle, RGBFloatPixel, Number, Number)
Buffer:SetDPI(Number, Number)
Buffer:SetIndexedLayer(Integer, Layer)
Buffer:SetIndexedLayer(Integer, Layer, String)
Buffer:SetIndexedLayerName(Integer, String)
Buffer:SetPixel(Integer, Integer, RGBFloatPixel, Number, Number)
Buffer:SetPixel(Point, RGBFloatPixel, Number, Number)
Buffer:SetSize(Integer, Integer)
Buffer:SetSize(Point)
Layer (derived from s3d.obj.Object)
This class has the following Purpose constant data members:
Layer.kAutoErase -> integer
Layer.kAutoThreshold -> integer
Layer.kDepth -> integer
Layer.kEmpty -> integer
Layer.kFullImage -> integer
Layer.kIllumination -> integer
Layer.kLuaDefault -> integer
Layer.kMotionBlur -> integer
Layer.kObjectIndex -> integer
Layer.kTexture -> integer
Layer.kUnknown -> integer
Layer.kVelocity -> integer
Every instance of this class has the following member methods:
Layer:BlitFrom(Layer, Rectangle, Point) -> boolean
Layer:Blur(Integer)
Layer:BytesPerRow() -> integer
Layer:Clone() -> s3d.image.Layer
Layer:CloneAtNewSize(Point) -> s3d.image.Layer
Layer:CopyFrom(Layer)
Layer:CreateDynamicPixel() -> s3d.image.DynamicPixel
Layer:Erase(Rectangle)
Layer:FamilyID() -> integer
Layer:Fill(Rectangle, DynamicPixel)
Layer:Flip(Boolean, Boolean)
Layer:GetBackground() -> s3d.image.RGBA32Pixel
Layer:GetDithering() -> integer
Layer:GetFloatPixel(Integer, Integer, Number [modifiable reference])
Layer:GetForeground() -> s3d.image.RGBA32Pixel
Layer:GetFractionalPixel(Number, Number, DynamicPixel)
Layer:GetIndexPixel(Integer, Integer) -> integer
Layer:GetOriginalSize() -> s3d.vec.Point
Layer:GetPixel(Integer, Integer, DynamicPixel)
Layer:GetPurpose() -> integer
Layer:GetRGB32Pixel(Integer, Integer) -> s3d.image.RGBFloatPixel
Layer:GetRGB32Pixel(Integer, Integer, RGBFloatPixel [modifiable reference])
Layer:GetRGBA32Pixel(Integer, Integer) -> s3d.image.RGBA32Pixel
Layer:GetRGBA32Pixel(Integer, Integer, RGBA32Pixel [modifiable reference])
Layer:GetRGBAFloatPixel(Integer, Integer) -> s3d.image.RGBAFloatPixel
Layer:GetRGBAFloatPixel(Integer, Integer, RGBAFloatPixel [modifiable reference])
Layer:GetSaveFlag() -> boolean
Layer:GetSize() -> s3d.vec.Point
Layer:GetUpdated() -> boolean
Layer:Invert(Rectangle)
Layer:IsMipMapped() -> boolean
Layer:MergeFrom(Layer, Rectangle, Point) -> boolean
Layer:PaintPixel(Integer, Integer)
Layer:PixelID() -> integer
Layer:PixelSize() -> integer
Layer:SetBackground(RGBA32Pixel)
Layer:SetDithering(Integer)
Layer:SetFloatPixel(Integer, Integer, Number)
Layer:SetForeground(RGBA32Pixel)
Layer:SetIndexPixel(Integer, Integer, Integer)
Layer:SetPixel(Integer, Integer, DynamicPixel)
Layer:SetPurpose(Integer)
Layer:SetRGB32Pixel(Integer, Integer, RGBFloatPixel)
Layer:SetRGBA32Pixel(Integer, Integer, RGBA32Pixel)
Layer:SetRGBAFloatPixel(Integer, Integer, RGBAFloatPixel)
Layer:SetSaveFlag(Boolean)
Layer:SetSize(Integer, Integer)
Layer:SetSize(Point)
Layer:SetUpdated(Boolean)
Layer:StretchBlitFastFrom(Layer, Rectangle, Rectangle) -> boolean
Layer:StretchBlitFrom(Layer, Rectangle, Rectangle) -> boolean
Layer:StretchBlitMaskedFrom(Layer, Layer, Rectangle, Rectangle) -> boolean
DynamicPixel
Instances of this class may only be created by the CreateDynamicPixel class function or the CreateDynamicPixel pixel method for each predefined pixel class. A dynamic pixel object can be used to communicate pixel values without needing to get specific about the actual underlying pixel representation.
Every instance of this class has the following member methods:
DynamicPixel:GetPixelID () -> integer
Returns the pixel type for the contained pixel. This matches the value returned by the pixelClass.kType class constant.
DynamicPixel:GetPixelPtr () -> s3d.util.Memory
Returns an s3d.util.Memory object referencing the internal pixel storage.
DynamicPixel:SetPixelData (newData)
newData -> s3d.util.Memory
Sets the data for the contained pixel using an s3d.util.Memory argument.
Accessor methods:
DynamicPixel:GetIndexPixel () > s3d.image.IndexPixel
Returns the value for the contained pixel as if it were an IndexPixel.
DynamicPixel:GetFloatPixel () -> s3d.image.FloatPixel
Returns the value for the contained pixel as if it were a FloatPixel.
DynamicPixel:GetRGBA32Pixel () -> s3d.image.RGBA32Pixel
Returns the value for the contained pixel as if it were an RGBA32Pixel.
DynamicPixel:GetRGBFloatPixel () -> s3d.image.RGBFloatPixel
Returns the value for the contained pixel as if it were an RGBFloatPixel.
DynamicPixel:GetRGBAFloatPixel () -> s3d.image.RGBAFloatPixel
Returns the value for the contained pixel as if it were an RGBAFloatPixel.
Modification methods:
DynamicPixel:SetIndexPixel (newValue)
newValue -> s3d.image.IndexPixel
Sets the value for the contained pixel as if it were an IndexPixel.
DynamicPixel:SetFloatPixel (newValue)
newValue -> s3d.image.FloatPixel
Sets the value for the contained pixel as if it were a FloatPixel.
DynamicPixel:SetRGBA32Pixel (newValue)
newValue -> s3d.image.RGBA32Pixel
Sets the value for the contained pixel as if it were an RGBA32Pixel.
DynamicPixel:SetRGBFloatPixel (newValue)
newValue -> s3d.image.RGBFloatPixel
Sets the value for the contained pixel as if it were an RGBFloatPixel.
DynamicPixel:SetRGBAFloatPixel (newValue)
newValue -> s3d.image.RGBAFloatPixel
Sets the value for the contained pixel as if it were an RGBAFloatPixel.
The following classes define typical pixel types used to communicate with Layer objects and to populate their pixel storage. All of these classes also incorporate methods detailed at the end of this page in Common Pixel Functions and Methods.
IndexPixel
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
IndexPixel ()
Constructs a new pixel with uninitialized values.
IndexPixel (init)
init -> integer
Constructs a new pixel with the given value, which may range over all 32-bit integer values.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "value" -> the value stored in this pixel
This class also includes everything in the section Common Pixel Functions and Methods below.
FloatPixel
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
FloatPixel ()
Constructs a new pixel with uninitialized values.
FloatPixel (init)
init -> integer
Constructs a new pixel with the given value, which may range over all single precision real numbers.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "value" -> the value stored in this pixel
This class also includes everything in the section Common Pixel Functions and Methods below.
Gray8Pixel
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
Gray8Pixel ()
Constructs a new pixel with uninitialized values.
Gray8Pixel (init)
init -> integer
Constructs a new pixel with the given value, ranging from 0 to 255.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "value" -> the value stored in this pixel
This class also includes everything in the section Common Pixel Functions and Methods below.
RGB15Pixel
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
RGB15Pixel ()
Constructs a new pixel with uninitialized values.
RGB15Pixel (red, green, blue)
red -> integer
green -> integer
blue -> integer
Constructs a new pixel with the given values, each ranging from 0 to 255.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "red"
2 | "green"
3 | "blue"
This class also includes everything in the section Common Pixel Functions and Methods below.
RGB24Pixel
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
RGB24Pixel ()
Constructs a new pixel with uninitialized values.
RGB24Pixel (red, green, blue)
red -> integer
green -> integer
blue -> integer
Constructs a new pixel with the given values, each ranging from 0 to 255.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "red"
2 | "green"
3 | "blue"
This class also includes everything in the section Common Pixel Functions and Methods below.
RGB32Pixel
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
RGB32Pixel ()
Constructs a new pixel with uninitialized values.
RGB32Pixel (red, green, blue)
red -> integer
green -> integer
blue -> integer
Constructs a new pixel with the given values, each ranging from 0 to 255.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "red"
2 | "green"
3 | "blue"
This class also includes everything in the section Common Pixel Functions and Methods below.
RGBA32Pixel
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
RGBA32Pixel ()
Constructs a new pixel with uninitialized values.
RGBA32Pixel (red, green, blue, alpha)
red -> integer
green -> integer
blue -> integer
alpha -> integer
Constructs a new pixel with the given values, each ranging from 0 to 255.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "red"
2 | "green"
3 | "blue"
4 | "alpha"
This class also includes everything in the section Common Pixel Functions and Methods below.
RGB48Pixel
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
RGB48Pixel ()
Constructs a new pixel with uninitialized values.
RGB48Pixel (red, green, blue)
red -> integer
green -> integer
blue -> integer
Constructs a new pixel with the given values, each ranging from 0 to 65535.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "red"
2 | "green"
3 | "blue"
This class also includes everything in the section Common Pixel Functions and Methods below.
RGBA64Pixel
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
RGBA64Pixel ()
Constructs a new pixel with uninitialized values.
RGBA64Pixel (red, green, blue, alpha)
red -> integer
green -> integer
blue -> integer
alpha -> integer
Constructs a new pixel with the given values, each ranging from 0 to 65535.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "red"
2 | "green"
3 | "blue"
4 | "alpha"
This class also includes everything in the section Common Pixel Functions and Methods below.
RGBFloatPixel
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
RGBFloatPixel ()
Constructs a new pixel with uninitialized values.
RGBFloatPixel (red, green, blue)
red -> number
green -> number
blue -> number
Constructs a new pixel with the given values, each ranging from 0 to 1,but capable of a range from -1.0e-30 to +1.0e-30.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "red"
2 | "green"
3 | "blue"
This class also includes everything in the section Common Pixel Functions and Methods below.
RGBAFloatPixel (derived from s3d.image.RGBFloatPixel)
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
RGBAFloatPixel ()
Constructs a new pixel with uninitialized values.
RGBAFloatPixel (red, green, blue, alpha)
red -> number
green -> number
blue -> number
alpha -> number
Constructs a new pixel with the given values, each typically ranging from 0 to 1
but capable of a range from -1.0e-30 to +1.0e-30.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "red"
2 | "green"
3 | "blue"
4 | "alpha"
This class also includes everything in the section Common Pixel Functions and Methods below.
RGBTFloatPixel (derived from s3d.image.RGBFloatPixel)
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
RGBTFloatPixel ()
Constructs a new pixel with uninitialized values.
RGBTFloatPixel (red, green, blue, transmission)
red -> number
green -> number
blue -> number
transmission -> number
Constructs a new pixel with the given values, each typically ranging from 0 to 1
but capable of a range from -1.0e-30 to +1.0e-30.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "red"
2 | "green"
3 | "blue"
4 | "transmission"
This class also includes everything in the section Common Pixel Functions and Methods below.
HalfFloatPixel
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
HalfFloatPixel ()
Constructs a new pixel with uninitialized values.
HalfFloatPixel (init)
init -> integer
Constructs a new pixel with the given value, typically ranging from 0 to 1 but capable of a range from -4095.0 to +4095.0.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "value" -> the value stored in this pixel
This class also includes everything in the section Common Pixel Functions and Methods below.
RGBHalfFloatPixel
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
RGBHalfFloatPixel ()
Constructs a new pixel with uninitialized values.
RGBHalfFloatPixel (red, green, blue)
red -> number
green -> number
blue -> number
Constructs a new pixel with the given values, each typically ranging from 0 to 1 but capable of a range from -4095.0 to +4095.0.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "red"
2 | "green"
3 | "blue"
This class also includes everything in the section Common Pixel Functions and Methods below.
RGBAHalfFloatPixel
This class has the following constant data members:
kType -> integer
This class has the following construction methods:
RGBAHalfFloatPixel ()
Constructs a new pixel with uninitialized values.
RGBAHalfFloatPixel (red, green, blue, alpha)
red -> number
green -> number
blue -> number
alpha -> number
Constructs a new pixel with the given values, each typically ranging from 0 to 1 but capable of a range from -4095.0 to +4095.0.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "red"
2 | "green"
3 | "blue"
4 | "alpha"
This class also includes everything in the section Common Pixel Functions and Methods below.
Common Pixel Class Functions and Methods
Every pixel class supports the following class function:
pixelClass.CreateDynamicPixel () -> s3d.image.DynamicPixel
Creates a dynamic pixel object holding a pixel instance of this class type and having uninitialized storage.
Every instance of a pixel class has the following member methods:
pixelClass:CreateDynamicPixel () -> s3d.image.DynamicPixel
Creates a dynamic pixel object holding a copy of this pixel.
pixelClass:IsEqual (other) -> boolean
other -> a pixel of the same type
Returns true if this pixel is equal to the other pixel.
Every instance of a pixel class also supports the following operators:
pixelClass:__eq (other) -> boolean
other -> a pixel of the same type
Available as the infix notation "=="
Returns the result of calling pixelClass:IsEqual (other).
pixelClass:__tostring () -> string
Available via the tostring() global Lua function, and called from many other places.
Returns a textual representation of this pixel.