loading

RoboRealm Server API - COM functions

The following COM functions are examples on how to use the provided COM object to execute certain functions against the RoboRealm API Server. Note that the function references are provided in CSharp format. When used in other languages you may have to check that language's capabilities for object passing. All provided examples assume that a connection has already been made to the RoboRealm API Server using something akin to: 


using RR_COM_APILib;

private const int VARIANT_TRUE = -1;
private const int VARIANT_FALSE = 0;

RR_COM_APILib.API_Wrapper rr = new API_Wrapper();

if (connection.Startup() == VARIANT_TRUE)
{
 ....
}
In other languages

set rr=CreateObject("RoboRealm.API.1")

if rr.Startup() <> 0 then
  ....

  rr.Disconnect()
end if
may be sufficient.

SetCOMType - Switches between API and DLL

The API (network connection to RoboRealm server) and the DLL (incorporate RoboRealm within your application) can be accessed using the same function calls mentioned here. It is normally best to start application integration using the API since the calls to RoboRealm can be made visible (assuming RoboRealm is used in GUI mode). Once the integration is complete, once can switch to using the DLL using the SetCOMType which will move the access type from the network based API to loading in the RoboRealm DLL instead. 

SetComType ( [input]0 or 1 )


rr.SetCOMType(1) ' sets the calls to use DLL instead of API.

Startup - Starting and connecting to RoboRealm

This request will attempt to connect to the RoboRealm API. If it fails, it will attempt to start the RoboRealm application with the API enabled. If that fails an error is returned. Note this uses registry information to determine where the RoboRealm.exe is stored. 

Startup ( )

return
	VARIANT_TRUE on success

if (rr.Startup()==VARIANT_TRUE)
{
...
}

Open - Starting RoboRealm

Creates a new RoboRealm program instance given the specified path. This is useful if you want better control over starting RoboRealm.exe from a specific folder. 

Open ( [input]filename, [input]port )

parameters
	filename - the RoboRealm.exe path/filename needed to create a new instance
	port - API port to use (typically 6060)

return
	VARIANT_TRUE on success

if (rr.Open("c:\\Program Files (x86)\\RoboRealm\\RoboRealm.exe", 6060)
	==VARIANT_TRUE)
{
	if (rr.Connect("localhost", 6060)==VARIANT_TRUE)
	{
	...
	}
}

OpenEx - Starting RoboRealm

Simliar to Open but adds an additional parameter to pass arguments to the RoboRealm.exe program. See API Parameters for what parameters are valid. 

OpenEx ( [input]filename, [input]args, [input]port)

parameters
	filename - the RoboRealm.exe path/filename needed to create a new instance
	args - program parameters (typically "-faceless")
	port - API port to use (typically 6060)

return
	VARIANT_TRUE on success

if (rr.OpenEx("c:\\Program Files (x86)\\RoboRealm\\RoboRealm.exe", 6060, "-faceless")
	==VARIANT_TRUE)
{
	if (rr.Connect("localhost", 6060)==VARIANT_TRUE)
	{
	...
	}
}

Connect - Connecting to RoboRealm

Opens a network connection to the RoboRealm API. If this fails, check that you have enabled the RoboRealm API by going to RoboRealm Interface->Options Button->API tab. 

Connect ( [input]hostname, [input]port )

parameters
	hostname - the machine name where RoboRealm is located
		(typically 'localhost' or '127.0.0.1')
	port - API port to use (typically 6060)

return
	VARIANT_TRUE on success

if (rr.Open("c:\\Program Files (x86)\\RoboRealm\\RoboRealm.exe", 6060)==VARIANT_TRUE)
{
	if (rr.Connect("localhost", 6060)==VARIANT_TRUE)
	{
	...
	}
}

IsConnected - Indicates active connection

Returns true or false depending on if an active connection is currently connected to RoboRealm. 

IsConnected ( )

return
	true - a good connection is currently present
	false - connection lost


if (!rr.IsConnected())
{
	if (rr.Connect("localhost", 6060)==VARIANT_TRUE)
	{
	...
	}
}

SetTimeout - Sets connection timeout

Sets the network connection timeout parameter. This is by default set to 30 seconds (30000) but this can be too long or short if your connection tends to fail. If you connection to RoboRealm fails the timeout specifies how long the API will wait until it determines the connection to have failed. 

SetTimeout ( [input] timeout_ms )

return
	timeout_ms - milliseconds to wait on any connection to the API server


rr.SetTimeout (1000);

SetAutoReconnect - Sets reconnection mode

If a connection is lost to RoboRealm, the COM object will attempt to reconnect and issue the same request. If your connection also requires initialization to setup a known state in RoboRealm you will want to DISABLE this and instead use the IsConnected function to determine network connection failure such that you can re-connect and then initialize the state as needed. 

SetAutoReconnect ( [input] true_false )

return
	true - attempt to reconnect if a connection fails
	false - do not attempt to automatically reconnect


rr.SetAutoReconnect (false);

GetDimension - Getting the current image dimensions

This request will return the dimensions of the source, processed or a specified marked image. Note that these dimensions can be different from the camera dimensions due to usage of modules like scaling or cropping. To get the current camera width and height see get_camera_format below. 

GetDimension([output]width, [output]height)

parameters
	width, height - integer variables that will contain the width and height
		of the current image

return
	VARIANT_TRUE on success

object width, height;
if (rr.GetDimension(out width, out height)==VARIANT_TRUE)
{
	Console.WriteLine("Size: "+(int)width+" "+(int)height);
}

GetImage - Reading an image

This request will return the currently processed image as seen in RoboRealm as RGB triplet data or in the specified format. 

GetImage ([input]name, [output]image_data, [output]width, [output]height, [input]format)

parameters
	name - can be one of "source", "processed", or a marker name defined
		in the image processing pipeline.
	image_data - object that will contain the image data
	width, height - integer variables that will contain the width and height
		of the image data
	format -
			RGB - Image data is 3 byte RGB triplet. (largest size)
			GRAY - Image data is a single byte gray level ((R+G+B)/3)
			RED - Image data is the single byte red channel
			GREEN - Image data is the single byte green channel
			BLUE - Image data is the single byte blue channel
			BINARY - Image data per byte is 8 pixel binary
				representing a black and white image. (smallest size
				but lowest intensity/color)
			JPEG - A compressed JPEG image with header information

object image;
int numBytes = rr.GetImage("", out image, out width, out height, "RGB");
object[] rgbArray = (object[])image;
Console.WriteLine("First Pixel: " + rgbArray[0] + "," + rgbArray[1] + "," + rgbArray[2]);

SetCOMParameter - Sets an extended parameter for the GetImage function

This function does not generate any messages but is used to configure the GetImage function in more ways than can be specified in the function call. 

SetCOMParameter ([input]name, [input]value)

parameters
	name - can be one of "image_greyscale" or "image_quality"
	value
		- image_grayscale - 1 or 0 to ensure that only gray values are returned
		- image_quality - 1 to 5 depending on the jpeg compression with 1 being
          the worst and 5 as the best

object image;
int numBytes = rr.GetImage("", out image, out width, out height, "RGB");
object[] rgbArray = (object[])image;
Console.WriteLine("First Pixel: " + rgbArray[0] + "," + rgbArray[1] + "," + rgbArray[2]);

SetImage - Writing an image

This request allows you to update the current image in RoboRealm with the provided image. Note that if the camera is enabled the source image will quickly be overwritten by the next video frame. You can also use this routine to set marker images (images just kept in memory) that are used by some modules. 


SetImage ([input]name, [input]image_data, [input]width, [input]height, [input]format)

parameters
	name - can be one of "source", "processed", or a marker name defined
		in the image processing pipeline.
	image_data - object that contains the image data
	width, height - image data dimensions
	format -
			RGB - Image data is 3 byte RGB triplet. (largest size)
			GRAY - Image data is a single byte gray level ((R+G+B)/3)
			RED - Image data is the single byte red channel
			GREEN - Image data is the single byte green channel
			BLUE - Image data is the single byte blue channel
			BINARY - Image data per byte is 8 pixel binary
				representing a black and white image. (smallest size
				but lowest intensity/color)
			JPEG - A compressed JPEG image with header information

int i;
byte[] rgbArray = new byte[320 * 240 * 3];
for (i=0;i<320*240*3;i++)
	rgbArray[i] = (byte)(i&255);
object image = (object)rgbArray;
rr.SetImage("", ref image, 320, 240, "RGB");

GetBitmap - Reading a bitmap image

Similar to GetImage, this request will return the specified image as a bitmap formatted image that is often easier to work with than raw RGB triplet data. Note that a bitmap assumes a format and size as appropriate to the current image. 

GetBitmap ([input]name )

parameters
	name - can be one of "source", "processed", or a marker name defined
		in the image processing pipeline.

[DllImport("gdi32.dll")]
public static extern bool DeleteObject(IntPtr hObject);

Bitmap bmpToDisplay = null;
IntPtr hBitmap = (IntPtr)connection.GetBitmap("processed");
if (hBitmap.ToInt32() != 0)
{
	bmpToDisplay = Image.FromHbitmap(hBitmap);
	DeleteObject(hBitmap);
}

SetBitmap - Writing a bitmap image

Similar to SetImage, this request will send the specified image as a bitmap formatted image to RoboRealm. Note that a bitmap assumes a format and size as appropriate to the current image. 

SetBitmap ([input]name, [input]bitmapHandle )

parameters
	name - can be "source" or a marker name defined
		in the image processing pipeline.
	bitmapHandle - pointer to a valid bitmap

[DllImport("gdi32.dll")]
public static extern bool DeleteObject(IntPtr hObject);

IntPtr hBitmap = bmpToDisplay.GetHbitmap();
if (hBitmap.ToInt32() != 0)
{
	object bit = (object)hBitmap;
	connection.SetBitmap("Source", hBitmap.ToInt32());
	DeleteObject(hBitmap);
}

GetVariable - Reading a variable

This request will read a variable from RoboRealm and return its value. The variable can be set by other API requests or RoboRealm modules. The type returned is always a string regardless of the variable type. 


str = GetVariable ([input]name)

parameters
	name - the name of the variable to query

return
	str - The value of the specified variable


string str = rr.GetVariable("IMAGE_COUNT");
int imageCount = Convert.ToInt32(str);

GetVariables - Reading several variables

This request is exactly like the request above with the exception that it will read in several variables in one request which is more efficient if you want to read more than one variable at a time. 

object = GetVariables([input] names)

parameters
	name - list of variable names as a single string comma delimited

return
	object - string array of results

object res = rr.GetVariables("IMAGE_COUNT, MOUSE_X, MOUSE_Y");
object[] values = (object[])res;
Console.WriteLine("Count: " + values[0] + " MouseX: " + values[1] + " MouseY: " + values[2]);

GetAllVariables - Reading all variables

This request is exactly like the request above with the exception that it will read in all variables in one request. 

count = GetAllVariables ([input,output]names, [ouput]values)

parameters
	names - array to contain the variable names
	values - array to contains the variable values

return
	count - number of variables contained within names, and values

object nameArray = new object();
object valueArray;
int num = rr.GetAllVariables(ref nameArray, out valueArray);
object[] names = (object[])nameArray;
object[] values = (object[])valueArray;
int i;
for (i=0;i<num;i++)
	Console.WriteLine(names[i] +"="+ values[i]);

SetVariable - Writing a variable

This request will set a variable into RoboRealm for use by other modules. 


SetVariable ([input]name, [input]value)

parameters
	name - the name of the variable to set
	value - the value of the variable

rr.SetVariable("my_var", "1234");

SetVariables - Writing multiple variables

This request is exactly the same as the request above with the exception that it will set multiple variables in RoboRealm. 

SetVariables ([input]names, [input]values)

parameters
	names - object array of variable names
	values - object array of variable values

object[] nameArray = { "var1", "var2", "var3" };
object[] valueArray = { "1234", "5678", "9012" };
object names = (object)nameArray;
object values = (object)valueArray;
rr.SetVariables(names, values);

GetArrayVariable - Reading an array

This request will get a variable array from RoboRealm. This is assumed to be a string array. 

GetArrayVariable ( [input]name, [output]values )

parameters
	name - name of the variable array to get
	values - container of the values of the array

object my_values = new object();
rr.GetArrayVariable("my_array", out my_values);

GetIntArrayVariable - Reading an integer array

This request will get a integer variable array from RoboRealm. 

GetIntArrayVariable ( [input]name, [output]values )

parameters
	name - name of the variable array to get
	values - container of the values of the array

object my_values = new object();
rr.GetIntArrayVariable("my_array", out my_values);

GetFloatArrayVariable - Reading a float array

This request will get a float variable array from RoboRealm. 

GetFloatArrayVariable ( [input]name, [output]values )

parameters
	name - name of the variable array to get
	values - container of the values of the array

object my_values = new object();
rr.GetFloatArrayVariable("my_array", out my_values);

SetArrayVariable - Writing an array

This request will set a variable array into RoboRealm for use by other modules. 

SetArrayVariable name, values

parameters
	name - name of the variable array to set
	values - the values of the array (assuming more than 1)

object[] valueArray = { 1,2,3,4,5,6,7,8,9 };
object values = (object)valueArray;
rr.SetArrayVariable("my_array", values);

DeleteVariable - Deleting a variable

This request will delete a variable from RoboRealm. 

DeleteVariable ([input]name);

parameters
	name - The name of the variable to delete

rr.DeleteVariable("my_array");

Execute - Executing a custom image processing sequence

This request allows you to specify a custom image processing sequence that RoboRealm will execute. You can create the appropriate string by using the RoboRealm GUI application, save the configuration in a .robo file and then paste its contents into the parameter for this request. 

Execute ([input]xml)

parameters
	xml - the XML string that specifies a pipeline configuration, aka robofile.

rr.Execute("<Rotate><mode>-90</mode></Rotate>");

LoadProgram - Loading a .robo program

This request will load a .robo processing pipeline file into RoboRealm. Note that the file needs to exist on the machine running RoboRealm. This is similar to pressing the 'open' button in the main RoboRealm dialog. 


LoadProgram ([input] filename )

parameters
	filename - filename of the robofile to load and execute in RoboRealm

rr.LoadProgram("c:\\temp\\test.robo");

SaveProgram - Saving a .robo program

This request will save a .robo processing pipeline file from RoboRealm. This is similar to pressing the 'save' button in the main RoboRealm dialog. 

SaveProgram ([input] filename )

parameters
	filename - filename of the robofile to save from RoboRealm

rr.SaveProgram("c:\\temp\\test.robo");

GetProgram - Getting the current .robo program

This request will return the current loaded .robo pipeline as XML from RoboRealm. 

string = GetProgram ()

returns
	string - the current XML text that represents the RoboRealm pipeline

string str = rr.GetProgram();

SetParameter - Changing a module parameter

This request allows you to modify a module parameter as seen in the GUI interface. In some modules you can replace the static number/text with a [variable] specification but not all GUI number/text items support this format. Instead you can use this API call to directly change a parameter within that interface. 

SetParameter ([input]module_name, [input]module_count, [input]para_name, [input]para_value)

parameter

	module_name - the name of the module to modify (eg. Color_Filter)
	module_count - which module to modify in case you have
		more than one module of the same name (i.e. two Color_Filter modules).
	parm_name - the parameter to modify as seen in the XML string of the robofile
		(eg. min_distance)
  param_value - what to change the parameter value to (eg. 65)

rr.SetParameter("RGB_FILTER", 1, "min_value", "20");

GetParameter - Reading a module parameter

This request allows you to read a module parameter as seen in the GUI interface. 

GetParameter ([input]module_name, [input]module_count, [input]para_name)

parameter

	module_name - the name of the module to modify (eg. Color_Filter)
	module_count - which module to modify in case you have
		more than one module of the same name (i.e. two Color_Filter modules).
	parm_name - the parameter to modify as seen in the XML string of the robofile
		(eg. min_distance)

string minValue = rr.GetParameter("RGB_FILTER", 1, "min_value");

DeleteModule - Deleting a module

This request allows you to delete a particular module in the pipeline. The module to delete can be referred to by a name and number. The number is optional as not all pipelines will contain more than one occurrence of the same module. 

DeleteModule ([input] module_name, [input]module_count)

parameter

	module_name - the name of the module to delete (eg RGB_FILTER)
	module_count - which module to reference in case you have
		more than one module of the same name (i.e. two Color_Filter modules).

rr.DeleteModule("RGB_Filter", 1);

DeleteModuleAtLine - Deleting a module

This request allows you to delete a particular module in the pipeline. The module to delete can be referred to by the line number within the RoboRealm pipeline. 

DeleteModule ([input] line_number )

parameter
	line_number - the line number of the module to delete (eg 12)

rr.DeleteModuleAtLine(2);

NewPipeline - Clearing the Pipeline

This request removes all modules from the pipeline as if a user pressed the New button. 

NewPipeline ( )

rr.NewPipeline();

InsertModule - Insert a module

This request allows you to add a module to the end of the pipeline. Note, all default values for the module are assumed. Once inserted, you can use SetParamter to change values as needed. 

InsertModule ([input] module_name, [input] module_fields )

parameter

	module_name - the name of the module to delete (eg RGB_FILTER)
	module_fields - the XML string that represents the initial fields
		of the module being inserted

rr.InsertModule("RGB_Filter", "<hue_value>50</hue_value><channel>2</channel>");

InsertModuleAtLine - Insert a module

This request allows you to insert a module into a specific line in pipeline. Note, all default values for the module are assumed. Once inserted, you can use SetParamter to change values as needed. 

InsertModuleAtLine ( [input] line_number, [input] module_name, [input] module_fields  )

parameter

	line_number - the line number of the module to insert (eg 12)
	module_name - the name of the module to delete (eg RGB_FILTER)
	module_fields - the XML string that represents the initial fields
		of the module being inserted

rr.InsertModuleAtLine(3, "RGB_Filter", "<hue_value>50</hue_value><channel>2</channel>");

InsertModuleInTabAtLine - Insert a module

This request allows you to insert a module into a specific line in pipeline. Note, all default values for the module are assumed. Once inserted, you can use SetParamter to change values as needed. 

InsertModuleAtLine ( [input] tab_name, [input] line_number, [input] module_name,
	[input] module_fields  )

parameter

	tab_name - the name of the tab in which to insert the module into
	line_number - the line number of the module to insert (eg 12)
	module_name - the name of the module to delete (eg RGB_FILTER)
	module_fields - the XML string that represents the initial fields
		of the module being inserted

rr.InsertModuleAtLine(3, "RGB_Filter", "<hue_value>50</hue_value><channel>2</channel>");

DisableModule - Disabling a module

This request allows you to disable a particular module in the pipeline. The module to disable is referred to by a name and number. The number is optional as not all pipelines will contain more than one occurrence of the same module. Once disabled, the module will cease to function but remain within the pipeline. 

DisableModule ([input] module_name, [input]module_count)

parameter

	module_name - the name of the module to disable (eg RGB_FILTER)
	module_count - which module to reference in case you have
		more than one module of the same name (i.e. two Color_Filter modules).

rr.DisableModule("RGB_Filter", 1);

DisableModuleAtLine - Disabling a module

This request allows you to disable a module on a specified line in the pipeline. Once disabled, the module will cease to function but remain within the pipeline. 

DisableModuleAtLine ([input] line_number )

parameter
	line_number - the line number of the module to disable (eg 12)

rr.DisableModuleAtLine(12);

EnableModule - Enabling a module

This request allows you to enable a particular module in the pipeline. The module to enable is referred to by a name and number. The number is optional as not all pipelines will contain more than one occurrence of the same module. Once enable the module once again function within the pipeline. 

EnableModule ([input] module_name, [input]module_count)

parameter

	module_name - the name of the module to enable (eg RGB_FILTER)
	module_count - which module to reference in case you have
		more than one module of the same name (i.e. two Color_Filter modules).

rr.EnableModule("RGB_Filter", 1);

EnableModuleAtLine - Enabling a module

This request allows you to enable a module on a particular line in the pipeline. Once enable the module once again function within the pipeline. 

EnableModuleAtLine ( [input]line_number )

parameter
	line_number - the line number of the module to disable (eg 12)

rr.EnableModuleAtLine(2);

GetModuleTime - Getting the processing time of a module

This request will reply back with the timing (the numbers seen in the right hand side of the processing pipeline in the main RoboRealm GUI) information about each module or about a specific module. The module to query is referred to by a name and number. The number is optional as not all pipelines will contain more than one occurrence of the same module. If none are given the timing information about all the modules currently in the pipeline are returned. Results are in milliseconds (second/1000) 

int = GetModuleTime ([input] module_name, [input]module_count)

parameter

	module_name - the name of the module to get timing results from (eg RGB_FILTER)
	module_count - which module to reference in case you have
		more than one module of the same name (i.e. two Color_Filter modules).

int msec = rr.GetModuleTime("RGB_Filter", 1);

LoadImage - Loading an image into RoboRealm

This request will load an image into RoboRealm. Note that the image needs to exist on the machine running RoboRealm. Valid image formats include gif, pgm, ppm, jpg, png, bmp, and tiff. This is similar to pressing the 'load image' button in the main RoboRealm dialog. 

LoadImage ([input] name, [input] filename )

parameters
	name - the marker name the image is identified as. Can be "source" or
		a marker name.
	filename - name of the image file to load (.jpg, .png, .gif, etc)

rr.LoadImage("", "c:\\Program Files (x86)\\RoboRealm\\remo.jpg");

SaveImage - Saving an image

This request will save an image from RoboRealm to disk. Note that the image filename is relative to the machine running RoboRealm. Valid image formats include gif, pgm, ppm, jpg, png, bmp, and tiff. This is similar to pressing the 'save image' button in the main RoboRealm dialog. 


SaveImage ([input] name, [input] filename )

parameters

    name - the name the image is identified as. Can be source, processed or a marker name.
    filename - the image filename to save the image to (may or may not exist).

rr.SaveImage("", "c:\\temp\\test.jpg");

SetCurrentCamera/SetCamera - Setting the active camera

Sets the current camera driver. This can be used to change the current viewing camera to another camera installed on the same machine. Note that this is a small delay when switching between cameras. The specified name needs only to partially match the camera driver name seen in the dropdown picklist in the RoboRealm options dialog. For example, specifying "Logitech" will select any installed Logitech camera including "Logitech QuickCam PTZ". This is similar to selecting a different camera driver from the options dialog window. 

SetCurrentCamera ([input] camera_name )

parameters
	  camera_name - the camera driver name that you want to switch processing to OR
    can be on, off in order to stop the active camera.


rr.SetCamera("logitech");

GetCameras - Get camera list

Returns back all the cameras that RoboRealm can connect to. This can be used to provide users with a list of cameras that can be selected. 

GetCameras ([output]names)

parameters
	names - an object array of camera names that are available to RoboRealm

return
	int - number of cameras available


object names;
int num = rr.GetCameras(out names);
object[] cameras = (object[])names;
Console.WriteLine("First camera: " + cameras[0]);

GetCurrentCamera - Getting the currently active camera driver name

Returns back all current camera drivers in use by RoboRealm. This can be used to indicate which cameras are currently being used in RoboRealm. The list is a comma seperated string of active camera names. 

string = GetCurrentCamera ()

return
	string - the currently active camera

string cam = rr.GetCurrentCamera();

SetCameraFormat - Setting the active camera's image format

Sets the format options for the current camera driver. This can be used to change the image size (width & height), frames per second rate (fps) and compression used by current camera. These values can be set manually using the Driver interface GUI accessed by clicking on the Options button -> Video Tab -> Video Format button.

Note that when switching capture sizes there will be a delay while the camera adjusts its parameters. 

SetCameraFormat ([input]width, [input]height, [input]fps, [input]format);

parameters
	width, height - size of the capture image
	fps - frame rate (typically 30)
	format - data format, depends on the camera (typically RGB24, YUV2, etc.)

rr.SetCameraFormat(640, 480, 30, "RGB24");

GetCameraFormat - Getting the active camera's format

Returns the format settings for the current camera. 

GetCameraFormat ( [output] width, [output]height, [output]fps, [output]format )

parameters
	width, height - will hold the current image dimensions
	fps - current frames per second
	format - current compression format

object width, height, fps, format;
rr.GetCameraFormat(out width, out height, out fps, out format);

GetCameraDialogs - Get camera dialog list

Returns back all the property dialogs that are associated with the active camera. This typically includes the Video Format and Video Capture dialog interfaces. Using this list you can determine what property pages can be displayed to allow the user to configure the image properties. 

GetCameraDialogs ( [output] dialogNames )

parameter
	dialogNames - object array of available camera dialogs


object dialogNames = new object();
rr.GetCameraDialogs(ref dialogNames);

ShowCameraDialog - Show camera dialog

Causes the specified property page to display such that the user can change the properties of the currently active camera. 


ShowCameraDialog ([input] dialog_name )

parameters

	dialog_name - name of the camera dialog (typically "Video Format" or "Video Source")


rr.ShowCameraDialog("Video Format");

SetCameraProperty - Setting one camera property

Sets a single camera property for the current camera using DirectX. Note that not all properties are supported by each camera.

Note that several properties also allow an automatic (auto) mode to be enabled or disabled. If enabled the manual value is ignored until automatic mode is disabled. 


SetCameraProperty ([input]name, [input]value, [input]automatic)

parameters
	name - property name
	value - property value
	automatic - boolean indicating if the setting should be automatic


rr.SetCameraProperties("brightness", "100", false);

SetCameraProperties - Setting the active camera's image capture properties

Sets the properties for the current camera using DirectX. Note that not all properties are supported by each camera. The list below is exhaustive and may not represent properties that you can set on your camera. These values are can be set manually using the Driver interface GUI accessed by clicking on the Options button -> Video Tab -> Video Capture button.

Below are indicated all possible values. You can reduce this list to just those values you wish to set and need not specify all possible values for each request.

Note that several properties also allow an automatic (auto) mode to be enabled or disabled. If enabled the manual value is ignored until automatic mode is disabled. 


SetCameraProperties ([input]names, [input]values, [input]automatic, count)

parameters
	names - array of property names
	values - array of property values
	count - number of properties to set


object[] names = { "brightness", "contrast", "exposure" };
object param1 = (object)names;
int []values = { 100, 50, 20 };
object param2 = (object)values;
int []automatic = { 0, 0, 0 };
object param3 = (object)automatic;

rr.SetCameraProperties(ref param1, ref param2, ref param3, 3);

GetCameraProperties - Getting the active camera's image capture properties

Gets the properties for the current camera using DirectX. Note that not all properties are supported by each camera. The returned list will be of those properties that DirectX reports as being functional. Despite this the list may still contain properties that do not have any effect on the camera.

Note that you can include only those properties that you wish to query in the request list. If no properties are specified then all property values are returned. 

GetCameraProperties ( [output] names, [output] values, [output] min, [output] max,
		[output] automatic, [input]num )

parameters
	names - will contain the list of property names
	values - will contain the list of current property values
	min - value minimums
	max - value maximums
	automatic - indicates if value is automatically determined


object names;
object values;
object min;
object max;
object automatic;
int num = rr.GetCameraProperties(out names, out values, out min, out max, out automatic, 64);

Run - Enable/Disable Processing

This request provides a way to stop processing incoming video. Some image processing tasks can be very CPU intensive and you may only want to enable processing when required but otherwise not process any incoming images to release the CPU for other tasks. The run mode can also be used to processing individual frames or only run the image processing pipeline for a short period. This is similar to pressing the "run" button in the main RoboRealm dialog. 

Run ( mode )

parameters
	mode - can be "toggle", "on", "off", "once", or a number of frames to process

rr.Run("Off");

Pause/Resume - Processing

The following request can be used to pause the RoboRealm pipeline processing. This is most useful if you need to query several variables in different requests that are dependent on each other. For example, you may request a variable with the length of another array variable. By pausing, reading, and then resuming the processing you can be sure that the variables are related to each other correctly and that a new value has not been created or an old one changed.

Note that once paused the application will appear to have locked. You must ensure to follow a pause with a resume command or restart the RoboRealm application to continue normal processing. 


Pause ()

Resume ()



rr.Pause()

rr.Resume()

WaitVariable - Waiting for RoboRealm

There is often a need to pause your own Robot Controller program to wait for RoboRealm to complete its task. The easiest way to accomplish this is to wait on a specific variable that is set to a specific value by RoboRealm. Using the wait_variable request you can pause execution and then continue when a variable changes within RoboRealm. 

WaitVariable ( var_name, var_value, timeout )

parameter

	var_name - name of the variable to wait for
	var_value - the value of that variable which will cancel the wait
	timeout - the maximum time to wait for the variable value to be set


rr.WaitVariable("IMAGE_COUNT", "100", 10000);

WaitImage - Waiting for a new image

If you are rapidly grabbing images you will need to wait inbetween each get_image for a new image to be grabbed from the video camera and processed. The waitImage request ensures that a new image has been processed and is available to grab. Without this routine you may be grabbing the same image more than once. 


WaitImage ( )

WaitImageFor ( timeout )


rr.WaitImage();

rr.WaitImage(2000);

EditModule - Editing a module

This request allows you to cause RoboRealm to display the GUI interface for a specific module. This works even when in faceless mode and allows your application to leverage the interfaces within RoboRealm without needing to recode what already exists. 

EditModule ( [input] name, [input] count )

parameters
	module_name - the name of the module to enable (eg RGB_FILTER)
	module_count - which module to reference in case you have
		more than one module of the same name (i.e. two Color_Filter modules).


rr.EditModule("RGB_Filter", 1);

EditModuleAtLine - Editing a module

This request allows you to cause RoboRealm to display the GUI interface for a module on the specified line number. This works even when in faceless mode and allows your application to leverage the interfaces within RoboRealm without needing to recode what already exists. 

EditModuleAtLine ( [input] line_number )

parameters
	line_number - the line number of the module to delete (eg 12)


rr.EditModuleAtLine(12);

MinimizeWindow - Minimizing RoboRealm Interface

The following request minimizes the RoboRealm interface such that it disappears into the task bar. 

MinimizeWindow

rr.MinimizeWindow();

MaximizeWindow - Maximizing RoboRealm Interface

The following request maximizes the RoboRealm interface such that it takes up the full screen. 

MaximizeWindow

rr.MaximizeWindow()

ResizeWindow - Resizing the RoboRealm Interface

The following request resizes the RoboRealm interface. Note that you can resize the interface below the recommended size where the interface can become mostly be unusable. 

ResizeWindow ( [input]width, [input]height )

parameters
	width - the width to set the RoboRealm GUI Interface
	height - the height to set the RoboRealm GUI Interface

rr.ResizeWindow(1024, 768);

MoveWindow - Moving the RoboRealm Interface

The following request moves the RoboRealm interface to a new location. Note that you can move the interface offscreen such that the user will not see the interface but will still know it is running as shown by the task bar. 

MoveWindow ( [input]X, [input]Y )

parameters
	X - horizontal location to set the top right of the RoboRealm Interface
	Y - vertical location to set the top right of the RoboRealm Interface

rr.MoveWindow(0, 0);

PositionWindow - Moving and Resizing the RoboRealm Interface

The following request moves and resizes the RoboRealm interface in one command. 

PositionWindow ( [input]X, [input]Y, [input]width, [input]height )

parameters
	X - horizontal location to set the top right of the RoboRealm Interface
	Y - vertical location to set the top right of the RoboRealm Interface
	width - the width to set the RoboRealm GUI Interface
	height - the height to set the RoboRealm GUI Interface

rr.PositionWindow(0, 0, 400, 400);

ShowWindow - Showing and Hiding the RoboRealm Interface

The following request will hide the RoboRealm interface 

ShowWindow ( [input] true|false )

parameter
	true|false - indicates if the main RoboRealm window show be hidden(false) or shown(true)

rr.ShowWindow(false);

EnterKiosk - Enter/exit Kiosk mode

The following request will enter/exit the Kiosk mode 

EnterKiosk ( [input] true|false )

parameter
	true|false - indicates if Kiosk mode should be activated(true) or exited(false)

rr.EnterKiosk(true);

Disconnect - Terminate API Connection

The following request will terminate the current API connection to the RoboRealm server BUT leave the RoboRealm application running. Any subsequent API commands will NOT work as the connection will have been terminated. For example, if you Disconnect and then Close the application will NOT Close since you have already terminated the API connection before the Close command was issued. In this case, just issuing a Close will accomplish the desired result. 

Disconnect ( )

rr.Disconnect()

Close - Exit RoboRealm Application

The following request closes RoboRealm in a nice manner. If you are running RoboRealm on the same machine that your API program is located you can use the "open" routine to start the RoboRealm process and this close request to terminate the application. Note this will also terminate the API connection since you are requesting the server to exit. 

Close ( )

rr.Close()

GetVersion - RoboRealm Version Number

This request returns the current version of RoboRealm running. This is a good test to see if the API is enabled as it is one of the most simplest API calls with the fewest dependencies on cameras, pipeline, etc. 

GetVersion

return
	Current RoboRealm Version X.Y.Z


Console.WriteLine(rr.GetVersion());


 New Post 
Related Forum PostsLast postPostsViews
Action after detection of Bullseye
I am running a drone with USB camera on RasPi 4B, I am able to detect the Bullseye using your file. Now after the ...		 1 year 1 919
VBscript module
Hi Roborealm Support, Inside my roborealm flow vision, I have added a vbscript program.
2 year 4 1545
how to download
how to download roborealm...		 3 year 1 1714
Calling a Tab through the API
Hi Y'all How do I make a call to a Tab thru the API?...		 4 year 1 1807
API / Integrate in VB.NET
Hello RR community, I have assigned project to work on and I'm wondering how exactly RR API works i...		 4 year 1 1914
rr.ShowWindow(false)
I'm working on setting up an API in C# using a commercial (x64) version 2.87.21 I'm displaying a ca...		 4 year 1 1894
Robustness of RR in Industrial application
I am planning to develop a machine vision application to test the light beam of automotive headlamp. This is an industrial appli...		 5 year 3 3469
Is RR Idle Yet?
I'm working in vb.net. I need to know when RR is Idle (done processing the pipeline)...		 5 year 3 2746
SetImage
Goodmorning, i'm working with RoboRealm and a linear Basler camera. W...		 5 year 2 2816
Using the API server
I followed the instructions on how to setup the API.  The test example is beings with issuing the following command st...		 6 year 7 3213