Script function

world.FilterPixel

Type

Method

Summary

Performs a filtering operation on one pixel

Prototype

long FilterPixel(long Pixel, short Operation, double Options);

Description

This applies the specified filtering operation to the pixel supplied (an RGB code).

This does largely the same thing as WindowFilter, except it operates on a single pixel (that is, a single RGB colour). This does the same operations (with the same codes as for WindowFilter) excepting the ones which require more than one pixel (like Blur, Sharpen, Find Edges, and Emboss).


Operation - the filter operation. At present, one of:

1 - Apply colour noise

2 - Apply monochrome noise

7 - Adjust Brightness (by adding Options to the pixel)

8 - Adjust Contrast

9 - Adjust Gamma

10 - Adjust Brightness for red channel only (by adding Options to the pixel)

11 - Adjust Contrast for red channel only

12 - Adjust Gamma for red channel only

13 - Adjust Brightness for green channel only (by adding Options to the pixel)

14 - Adjust Contrast for green channel only

15 - Adjust Gamma for green channel only

16 - Adjust Brightness for blue channel only (by adding Options to the pixel)

17 - Adjust Contrast for blue channel only

18 - Adjust Gamma for blue channel only

19 - Convert to grayscale - mix red/green/blue equally

20 - Convert to grayscale - mix 30% red + 59% green + 11% blue for normal perception

21 - Adjust Brightness (by multiplying Options by the pixel)

22 - Adjust Brightness for red channel only (by multiplying Options by the pixel)

23 - Adjust Brightness for green channel only (by multiplying Options by the pixel)

24 - Adjust Brightness for blue channel only (by multiplying Options by the pixel)

27 - Average - the pixel's average colour (that is, itself)


Single channel operations - the modes which specify a single channel (10 to 18, 22 to 24) operate on that colour channel only (red, green or blue) leaving the others untouched. Thus by, say, increasing brightness on the red channel you add to the red value, but leave green and blue alone, making the image look redder. However decreasing brightness on the red channel would make the image look more cyan (as cyan is the complementary colour to red).

The complementary colours are:

red / cyan
green / magenta
blue / yellow



Options - filtering options.


For the Noise filter:

A number from about 0 to 255 indicating how much noise to add.


For the Brightness (additive) filter:

A number from -255 to +255 to indicate the amount to increase (or decrease) the value of the pixel - by adding. A negative number will make it darker, a positive number will make it brighter.


For the Brightness (multiplicative) filter:

A number which is multiplied by the value of the pixel. A number less than 1 will make it darker, a number greater than 1 will make it brighter. However black (zero) will remain black.


For the Contrast filter:

A number to indicate the amount to multiply by the value of the pixel. Zero will make the picture zero contrast, that is totally grey. If you use 1 the pixel will be normal contrast (as each pixel is multiplied by 1). A value between 0 and 1 will be lower contrast. A value above 1 will increase contrast. Negative numbers will have the effect of making the image look negative.


For the Gamma filter:

A number to indicate the amount of Gamma adjustment. Mathematically the pixel is raised to the power of this number. Thus, a gamma of 1 will result in no change. A gamma of 2 will darken the image somewhat. A gamma of 0.5 will lighten the image. A gamma of zero will make the image totally white.
The difference between gamma and brightness is that increasing brightness simply adds to the value of each pixel, so that black becomes gray, and bright pixel become clipped. Similarly, decreasing brightness means that white pixels become grey, and dark ones are clipped.

However because gamma is a power function, black stays black, and white stays white, with the biggest change in the mid range. A higher gamma value results in a darker image with more contrast. A lower gamma value (between 0 and 1) results in a lighter image with less contrast.


For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

Available in MUSHclient version 4.36 onwards.

Lua example

-- Brightness

FilterPixel (0x445566, 7, -4) -- lower by 4 (gives 0x405162)
FilterPixel (0x445566, 7, 10) -- raise by 10 (gives 0x4e5f70)

FilterPixel (0x445566, 21, 0.5) -- halve the brightness (gives 0x222a33)
FilterPixel (0x445566, 21, 2) -- double the brightness (gives 0x88aacc)


-- Contrast

FilterPixel (0x445566, 8, 0.5) -- reduce (gives 0x626a73)
FilterPixel (0x445566, 8, 2) -- increase (gives 0x082a4c)


-- Gamma

FilterPixel (0x445566, 9, 0.3) -- brighter, lower contrast (gives 0xabb7c1)
FilterPixel (0x445566, 9, 1.5) -- darker, higher contrast (gives 0x233140)
FilterPixel (0x445566, 9, 5)   -- very dark and contrasty (gives 0x000102)

Lua notes

You can use the following constants for the Operation argument:

miniwin.filter_noise = 1
miniwin.filter_monochrome_noise = 2
miniwin.filter_brightness = 7
miniwin.filter_contrast = 8
miniwin.filter_gamma = 9
miniwin.filter_red_brightness = 10
miniwin.filter_red_contrast = 11
miniwin.filter_red_gamma = 12
miniwin.filter_green_brightness = 13
miniwin.filter_green_contrast = 14
miniwin.filter_green_gamma = 15
miniwin.filter_blue_brightness = 16
miniwin.filter_blue_contrast = 17
miniwin.filter_blue_gamma = 18
miniwin.filter_grayscale = 19
miniwin.filter_normal_grayscale = 20
miniwin.filter_brightness_multiply = 21
miniwin.filter_red_brightness_multiply = 22
miniwin.filter_green_brightness_multiply = 23
miniwin.filter_blue_brightness_multiply = 24
miniwin.filter_average = 27

Return value

-1 : filter mode not in the list above.

Otherwise, the filtered pixel as an RGB code

See Also ...

Topics

Scripting
Utilities

Functions

(AddFont) Adds a custom font for use by MUSHclient
(Base64Decode) Takes a base-64 encoded string and decodes it.
(Base64Encode) Encodes a string using base-64 encoding.
(BlendPixel) Blends a single pixel with another, using a specified blending mode
(ChangeDir) Changes the MUSHclient working directory
(CreateGUID) Creates a GUID - Global Unique Identifier
(EditDistance) Returns the Levenshtein Edit Distance between two words
(ErrorDesc) Converts a MUSHclient script error code into an human-readable description
(ExportXML) Exports a world item in XML format
(FixupEscapeSequences) Converts "escape sequences" like \t to their equivalent codes.
(FixupHTML) Fixes up text for writing as HTML
(FlashIcon) Flashes the MUSHclient icon on the Windows taskbar
(GenerateName) Generates a random character name
(GetClipboard) Gets the clipboard contents
(GetScriptTime) Returns the amount of time spent in script routines
(GetSoundStatus) Gets the status of a sound started by PlaySound
(GetUniqueID) Creates a unique ID for general use, or for making Plugin IDs
(GetUniqueNumber) Returns a unique number
(Hash) Produces a hash (checksum) of a specified piece of text
(Help) Shows help for a script function, or a list of functions
(ImportXML) Imports configuration data in XML format
(Menu) Creates a pop-up menu inside the command window
(Metaphone) Returns the metaphone code for the supplied word
(MoveMainWindow) Move and resize the main MUSHclient window
(MoveWorldWindow) Move and resize a world window
(MoveWorldWindowX) Move and resize a specific world window
(MtRand) Returns pseudo-random number using the Mersenne Twister algorithm
(MtSrand) Seed the Mersenne Twister pseudo-random number generator
(PlaySound) Plays a sound using DirectSound
(ReadNamesFile) Loads in a file for generating character names
(Replace) Replaces one substring with another
(SetBackgroundColour) Sets a background colour for the output window
(SetBackgroundImage) Sets a background image for the output window
(SetClipboard) Sets the clipboard contents
(SetForegroundImage) Sets a foreground image for the output window
(SetMainTitle) Sets the main output window title
(SetSelection) Sets a selection range in the output window
(SetStatus) Sets the status line text
(SetTitle) Sets the world window title
(SetToolBarPosition) Sets the position of the game toolbars on the screen.
(SetUnseenLines) Sets the number of "unseen lines" for this world
(ShiftTabCompleteItem) Adds an item to the list shown for Shift+Tab completion
(Simulate) Simulate input from the MUD, for debugging purposes
(Sound) Plays a sound
(StopSound) Stop playing a sound started by PlaySound
(StripANSI) Strips ANSI colour sequences from a string
(Trace) Trace mode property
(TraceOut) Outputs the supplied message to the world Trace
(TranslateDebug) Sends a debugging message to the localizing translator script
(TranslateGerman) Translate German umluat sequences
(Transparency) Sets the transparency of the main MUSHclient window under Windows XP
(Trim) Trims leading and trailing spaces from a string
(WindowFilter) Performs a filtering operation over part of the miniwindow.

(Help topic: function=FilterPixel)