General Information
This Xtra will only work on Macintosh computers.
Your computer must be connected to a source of video by an internal socket, third party video digitizing board or serial video camera such as the Connectix QuickCam.
This Xtra lets you create nasking effects on live video such as chroma keying and backgriound removal.
Getting in touch.
If you have suggestions, problems or comments about this Xtra you can write to :
info@smoothware.com
To find information about this Xtra and other Xtras, or to purchase this or another Xtra visit URL
www.smoothware.com
Opening the Xtra.
Put the Xtra in the "Xtras" folder near your Director application. Then call -
set temp = Xtra "VideoMask"
set MaskObj = new(temp)
Have MaskObj declared as a Global variable since you will be referring to it later.
You will probably be doing this in the beginning of the movie so your handler will probably look like this:
on StartMovie
Global MaskObj
if not MaskObj then
set temp = Xtra "VideoMask"
set MaskObj = new(temp)
end if
end StartMovie
Closing the Xtra.
When you are done you should close the Xtra by assigning 0 to the variable.
on StopMovie
global MaskObj
set MaskObj = 0
end
Starting the video flow.
In order to access the video stream, the Xtra has to establish a connection with the video capture device and allocate memory. None of the other methods in this Xtra will work without calling the InitVideo() first. You should call the InitVideo() method only once, and be sure to call CleanUp() before you leave.
The InitVideo(MaskObj, Width, height,source) method takes four arguments:
MaskObj - The instance number returned from New().
Height - defines the height in Pixels of the video frame you want.
Width - defines the width in Pixels of the video frame you want.
source - defines the video digitizer that will be used. In most cases use 1. If you have more than one video digitizers installed in your computer (for example an AV board and a Connectix camera) than you can specify 2 for the second 3 for the third... If you specify a number larger than the number of video digitizers in the computer it will default to the first.
The smaller the video frame the better the performance of the Xtra.
Stopping the video flow.
Once you are done, you should call the CleanUp() method. Do not attempt to call InitVideo() again without calling the CleanUp() first.
The CleanUp(MaskObj) method takes one argument.
MaskObj - The instance number returned from New().
Opening the Video Settings dialog box
To open the standard Video Settings dialog box which allows you to change the video source or change the parameters for your camera, use the VideoSettings() method. This is very useful for changing the brightness, saturation and contrast of the video to create better conditions for the masking.
The VideoSettings(MaskObj) takes one argument.
MaskObj - The instance number returned from New().
Viewing the video source on stage
To View the video source on the screen you should call ShowVideo()
The ShowVideo(MaskObj) method takes three arguments.
MaskObj - The instance number returned from New().
horizontal - The location in pixels of the left side of the frame.
vertical - The location in pixels of the top of the frame.
Please note that the ShowVideo() method should be called repeatedly, to get a continuously changing display of the video source.
The ShowVideo() method returns a list containing 3 numbers.
[red, green, blue] these numbers are the color value of the Pixel directly under the mouse the numbers go from 0 - 255 . This feature is useful for determining the color value of specific elements in the video, in order to track them later.
Grabbing a video frame to a cast member
You can use the Xtra to grab frames from the video to a cast member. This is useful for creating background images for visualizing the tracking and for other purposes.
To grab a video frame to a cast member use the GrabToCast() method.
The GrabToCast (MaskObj, CastMemberNum) takes two parameters.
MaskObj - The instance number returned from New().
CastMemberNum - The number of the cast member to which you wish to grab the frame. (Have an Image cast member waiting in that location)
Creating a reference frame for background removal
For background removal you need to give the Xtra a reference frame to compare to, this will probably be a frame of the background with no foreground objects in it. When the video is showing such a frame a call remember() the Xtra then takes a frame of the video and stores it in memory for reference . The Remember(MaskObj) method takes one parameter.
MaskObj - The instance number returned from New().
This is a good time to also grab a frame to a cast member for you to use as a reference by using GrabToCast() (see details above)
Setting video parameters directly
Sometimes you may want to set attributes of the video without opening the video settings dialog box . You can do that with the SetPararms() method.
The SetParams(MaskObj,input,hue,saturation,brightness,contrast,sharpness ,standard) method takes 8 arguments:
MaskObj - The instance number returned from New().
input - 1 or zero . 0 for composite video input. 1 for S-Video input. Not all video grabbers support this parameter. If you wish to leave the input untouched set this argument to -1
hue - a number between 0 and 65536 defining the hue of the video. A setting of 32768 is 180 degrees which is the normal setting. If you wish to leave the hue untouched set this argument to -1. Not all video grabbers support this parameter.
saturation - a number between 0 and 65536 defining the saturation of the video. A setting of 32768 is the normal setting. If you wish to leave the saturation untouched set this argument to -1. Not all video grabbers support this parameter.
brightness - a number between 0 and 65536 defining the brightness of the video. A setting of 32768 is the normal setting. If you wish to leave the brightness untouched set this argument to -1. Not all video grabbers support this parameter.
contrast - a number between 0 and 65536 defining the contrast of the video. A setting of 32768 the normal setting. If you wish to leave the contrast untouched set this argument to -1. Not all video grabbers support this parameter.
sharpness - a number between 0 and 65536 defining the sharpness of the video. A setting of 32768 the normal setting. If you wish to leave the sharpness untouched set this argument to -1. Not all video grabbers support this parameter.
standard - a number between 0 and 2. 0 for NTSC, 1 for PAL, 2 for SECAM. Not all video grabbers support this parameter. If you wish to leave the standard untouched set this argument to -1
Getting video parameters directly
Sometimes you may want to get attributes of the video without opening the video settings dialog box . You can do that with the SetPararms() method. this is handy for saving the settings for future use.
The GetParams(MaskObj) method takes one argument
MaskObj - The instance number returned from New().
The GetParams() method returns a list with 6 items : [input,hue,saturation,brightness,contrast,sharpness]
input - 1 or zero . 0 for composite video input. 1 for S-Video input. Not all video grabbers support this parameter.
hue - a number between 0 and 65536 defining the hue of the video. A setting of 32768 is 180 degrees which is the normal setting. Not all video grabbers support this parameter.
saturation - a number between 0 and 65536 defining the saturation of the video. A setting of 32768 is the normal setting. Not all video grabbers support this parameter.
brightness - a number between 0 and 65536 defining the brightness of the video. A setting of 32768 is the normal setting. Not all video grabbers support this parameter.
contrast - a number between 0 and 65536 defining the contrast of the video. A setting of 32768 the normal setting. Not all video grabbers support this parameter.
sharpness - a number between 0 and 65536 defining the sharpness of the video. A setting of 32768 the normal setting. Not all video grabbers support this parameter.
Sending parameters for the masking operation
To create, edit and display a mask, you call the mask() method. Notice that you should call this method only when changing parameters for the masking. If nothing has changed in your parameters then use UpdateMask().
The Mask(MaskObj,maskCreate,maskEdit,maskDisplay,maskOutput) method takes 5 arguments.
MaskCreate. This argument is a list containing all parameters required for the creation of a mask, i.e. Which portion of the frame should be included and which portions excluded. The MaskCreate parameter is made of 3 parameters which describe the 3 methods of defining areas to be included/excluded in the mask
MaskObj - The instance number returned from New().
IncludeColors - A list containing 4 parameters which define the colors to be included in the mask, you define a color by its RGB value and a tolerance threshold . If you do not wish to include colors you must pass an empty list, IncludeColors = [ ]
Red — A number between 0 — 255 that defines the red component of the colors you wish to include in the mask.
Green — A number between 0 — 255 that defines the green component of the colors you wish to include in the mask.
Blue — A number between 0 — 255 that defines the blue component of the colors you wish to include in the mask.
Tolerance — a number between 0 — 425 that defines how similar a pixel needs to be to the defined color in order to be included in the mask .
ExcludeColors - A list containing 4 parameters which define the colors to be excluded from the mask, you define a color by its RGB value and a tolerance threshold . If you do not wish to exclude colors you must pass an empty list, excludeColors = []
Red — A number between 0 — 255 that defines the red component of the colors you wish to exclude from the mask.
Green — A number between 0 — 255 that defines the green component of the colors you wish to exclude from the mask.
Blue — A number between 0 — 255 that defines the blue component of the colors you wish to exclude from the mask.
Tolerance — a number between 0 — 425 that defines how similar a pixel needs to be to the defined color in order to be excluded from the mask.
RemoveBackground - A list containing 2 parameters which define the background removal option. If you do not wish to remove the background you must pass an empty list, RemoveBackground = []
Remove — 1 to perform background removal, 0 not to perform background removal.
Tolerance — a number between 0 — 425 that defines how similar a pixel needs to be to the corresponding pixel in the reference frame to be included in the mask. You must use Remember() first to establish a reference frame.
MaskEdit. This argument includes all parameters for manipulating the mask. It is a list and can include multiple EditParam lists for performing multiple manipulations. If you do not wish to perform any manipulations you should pass an empty list, MaskEdit = [].
Each EditParam list includes 2 parameters
Manipulation - 1 for hole closing , 2 for creating an outline, 4 for growing / shrinking.
Amount — a number with the amount of the manipulation requested. For hole closing the amount is the size of holes (in pixels)that will be closed. For outline creation the amount is the width in pixels of the outline. For growing / shrinking the amount can be a positive number for the number of pixels to be added, or a negative number for the number of pixels to be removed.
MaskDisplay. This argument includes all the parameters for the display of the results. Here you define what the mask and the background will look like. The MaskDisplay is a list and it contains to parameters
Mask - The Mask parameter is a list that contains one of the following options :
1 Use the number 1 for defining a color for the masked areas. If you use this option you must also define the RGB levels of the color. Therefore Mask = [1,red,green,blue]
2 Use the number 2 for defining that the masked area will contain the live video. Therefore Mask = [2]
3 Use the number 3 for defining that the masked area will contain the reference frame. Therefore Mask = [3]
4 Use the number 4 for defining that the masked area will contain an image cast member. If you use this option you must also define the number of a member that will be used. Therefore Mask = [4,Member]
Background - The Background parameter is a list that contains one of the following options :
1 Use the number 1 for defining a color for the background areas. If you use this option you must also define the RGB levels of the color. Therefore Background = [1,red,green,blue]
2 Use the number 2 for defining that the background area will contain the live video. Therefore Background = [2]
3 Use the number 3 for defining that the background area will contain the reference frame. Therefore Background = [3]
4 Use the number 4 for defining that the background area will contain an image cast member. If you use this option you must also define the number of a member that will be used. Therefore Background = [4,MemberNum]
maskOutput — This argument includes the parameters for defining how the mask will be output. MaskOutput is a list and must contain one of the following options
1 Use the number 1 to send the mask to Director’s stage. If you use this option you must also define where on stage the mask will be displayed, you do that by defining the left,top,right, bottom of the display area. If this area is different from the video frame than the mask will be stretched to fit. Therefore maskOutput =[1,left,top,right,bottom]
2 Use the number 2 to send the mask to a image cast member. If you use this option you must also define the number of a member that will be used (make sure there is an image member in that location). Therefore maskOutput =[2,MemberNum]
updating the mask
To grab a new video frame and perform masking on it according to the parameters defined in mask(), use the MaskUpdate() method. The MaskUpdate(maskObj) takes one argument:
MaskObj - The instance number returned from New().
In its full description the Mask() method will look like this will look like this :
Mask(MaskObj, [IncludeColors, ExcludeColors, RemoveBackground],[EditParam, EditParam…],[Mask,Background], [MaskOutput]
A few examples :
To achieve background removal with a tolerance of 50, no manipulation, using member number 100 for the background and the live video for the mask, and displaying the mask on stage at location 0,0,320,240 the call would be :
mask(maskObj,[[], [], [1, 50]],[],[[4, 100], [2]],[1, 0, 0, 320, 240])
to create a blue screen effect using the color blue (0,0,255) with a tolerance of 50 , no manipulation , using a red color (255,0,0) for the background and live video for the mask, and displaying the mask on stage at location 0,0,320,240 the call would be :
mask(maskObj,[[[0, 0, 255, 50]], [], []],[],[[1, 255, 0, 0], [2]],[1, 0, 0, 320, 240])
To achieve background removal with a tolerance of 50, crate a 1 pixel outline, using black (0,0,0)for the background and white (255,255,255) for the mask, and sending the mask to member number 100 :
mask(maskObj,[[], [], [1, 50]],[[2, 1]],[[1, 0, 0, 0], [1, 255, 255, 255]],[2, 100])