RoboRealm Server API - XML messages

• Getting the current image dimensions
• Reading an image
• Writing an image
• Reading a variable
• Reading several variables
• Reading all variables
• Writing a variable
• Writing multiple variables
• Writing an array
• Deleting a variable
• Executing a custom image processing sequence
• Loading a .robo program
• Saving a .robo program
• Getting the current .robo program
• Changing a module parameter
• Reading a module parameter
• Inserting a module
• Deleting a module
• Toggle disabling of a module
• Getting the processing time of a module
• Loading an image into RoboRealm
• Saving an image
• Setting the active camera
• Get camera list
• Getting the currently active camera driver name
• Setting the active camera's image format
• Getting the active camera's format
• Get camera dialog list
• Show camera dialog
• Setting the active camera's image capture properties
• Getting the active camera's image capture properties
• Enable/Disable Processing
• Pausing/Resuming Processing
• Waiting for RoboRealm
• Waiting for a new image
• Editing a module
• Minimizing RoboRealm Interface
• Maximizing RoboRealm Interface
• Resizing the RoboRealm Interface
• Moving the RoboRealm Interface
• Moving and Resizing the RoboRealm Interface
• Showing and Hiding the RoboRealm Interface
• Quitting RoboRealm API
• RoboRealm Version Number
• Closing RoboRealm
• Formatting note

The following XML messages are direct examples that provide management functions outside of the image processing specifications found in the .robo files. These API routines mimic the buttons on the main RoboRealm dialog. Again, note that these are the raw requests that would be embedded in some network capable language. This reference is provided for those cases that cannot use the already compiled COM object to communicate with the RoboRealm Application. The COM object uses these exact messages to communicate with the application.

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.

<request>
    <get_dimension>IMAGE_NAME</get_dimension>
</request>

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

<response>
    <width>IMAGE_WIDTH</width>
    <height>IMAGE_HEIGHT</height>
</response>

Reading an image

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

<request>
    <get_image>
      <name>IMAGE_NAME</name>
      <format>RGB|GRAY|RED|GREEN|BLUE|BINARY|JPEG</format>
      <quality>JPEG_QUALITY</quality>
    </get_image>
</request>

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

FORMAT
   RGB - Image data is 3 byte RGB (red, green, blue) triplet.
   BGR - Image data is 3 byte BGR (blue, green, red) triplet.
   BGRA - Image data is 3 byte BGR with 1 alpha byte (blue, green, red, alpha) quad.
   FBGR - Image data a vertically flipped is 3 byte BGR (blue, green, red) triplet.
   FBGRA - Image data a vertically flipped is 3 byte BGR with 1 alpha byte (blue, green, red, alpha) quad.
   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.

JPEG_QUALITY - a number from 128 (really good) to 2048 (really bad) representing the jpeg compression quality. The default is 256 (good).

FBGR is the native format of images within Windows and thus is the native format of RoboRealm. Sending this format is the quickest format to import.

<response>
    <length>IMAGE_LENGTH</length>
    <width>IMAGE_WIDTH</width>
    <height>IMAGE_HEIGHT</height>
</response>
RGB triplet data ...

Note that the image data follows this response of length IMAGE_LENGTH.

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.

<request>
    <set_image>
        <name>IMAGE_NAME</name>
        <width>IMAGE_WIDTH</width>
        <height>IMAGE_HEIGHT</height>
        <format>RGB|GRAY|RED|GREEN|BLUE|BINARY</format>
        <wait>1</wait>
    </set_image>
</request>
RGB triplet data

OR

<request>
    <set_image>
        <compressed></compressed>
        <name>IMAGE_NAME</name>
        <size>SIZE</size>
        <wait>1</wait>
    </set_image>
</request>
compressed GIF, JPEG, etc. data depending on format setting...

compressed - indicates the data represents a GIF, JPEG, etc. image
SIZE - number of bytes in data stream, required for compressed data, optional for RGB
IMAGE_NAME - can either be source, processed or a new/existing marker name
FORMAT (non-compressed)
   RGB - Image data is 3 byte RGB triplet. (largest size)
   BGR - Image data is 3 byte BGR (blue, green, red) triplet.
   BGRA - Image data is 3 byte BGR with 1 alpha byte (blue, green, red, alpha) quad.
   FBGR - Image data a vertically flipped is 3 byte BGR (blue, green, red) triplet.
   FBGRA - Image data a vertically flipped is 3 byte BGR with 1 alpha byte (blue, green, red, alpha) quad.
   GRAY - Image data is a single byte gray level
   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. (smallest size)
WAIT - causes RoboRealm to finish processing the image before returning the set_image result. Thus, you can perform a get_variable after this routine and be guaranteed that the value was processed from the set_image call.

FBGR is the native format of images within Windows and thus is the native format of RoboRealm. Sending this format is the quickest format to import.

<response>ok</response>

OR

<response>timeout</response>

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.

<request>
    <get_variable>VAR_NAME</get_variable>
</request>

VAR_NAME - the name of the variable to query

<response><VAR_NAME>VAR_VALUE</VAR_NAME></response>

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.

<request>
  <get_variables>VAR_1_NAME, VAR_2_NAME, etc.</get_variables>
</request>

VAR_X_NAME - the name of a variable to query

<response>
    <VAR_1_NAME>VAR_1_VALUE</VAR_1_NAME>
    <VAR_2_NAME>VAR_2_VALUE</VAR_2_NAME>
    <VAR_3_NAME>VAR_3_VALUE</VAR_3_NAME>
</response>

Reading all variables

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

<request>
    <get_all_variables></get_all_variables>
</request>

<response>
    <VAR_1_NAME>VAR_1_VALUE</VAR_1_NAME>
    <VAR_2_NAME>VAR_2_VALUE</VAR_2_NAME>
    <VAR_3_NAME>VAR_3_VALUE</VAR_3_NAME>
</response>

Writing a variable

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

<request>
    <set_variable>
        <name>VAR_NAME</name>
        <value>VAR_VALUE</value>
    </set_variable>
</request>

VAR_NAME - the name of the variable to set VAR_VALUE - the value of the variable

<response>ok</response>

Writing multiple variables

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

<request>
    <set_variables>
        <variable>
            <name>VAR_1_NAME</name>
            <value>VAR_1_VALUE</value>
        </variable>
        <variable>
            <name>VAR_2_NAME</name>
            <value>VAR_2_VALUE</value>
        </variable>
        <variable>
            <name>VAR_3_NAME</name>
            <value>VAR_3_VALUE</value>
        </variable>
    </set_variables>
</request>

VAR_X_NAME - the name of one of the variable to set VAR_X_VALUE - the value of one of the variable to set

<response>ok</response>

Writing an array

This request will set a variable array into RoboRealm for use by other modules. Each array element is delimited by a comma.

<request>
    <set_variable>
        <name>VAR_NAME</name>
        <value>VAR_VALUE</value>
    </set_variable>
</request>

VAR_NAME - the name of the variable to set (my_list) VAR_VALUE - the value of the variable (1,2,3,4,5)

<response>ok</response>

Deleting a variable

This request will delete a variable from RoboRealm.

<request>
    <delete_variable>VAR_NAME</delete_variable>
</request>

VAR_NAME - the name of the variable to delete

<response>ok</response>

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.

<request>
    <execute>XML_STRING</execute>
</request>

XML_STRING - the image processing sequence to execute

<response>ok</response>

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.

<request>
    <load_program>FILENAME</load_program>
</request>

FILENAME - the name of the RoboRealm filename to load and execute

<response>ok</response>

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.

<request>
    <save_program>FILENAME</save_program>
</request>

FILENAME - the name of the RoboRealm filename to save

<response>ok</response>

Getting the current .robo program

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

<request>
    <get_program></get_program>
</request>

<response>XML_STRING</response>

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.

<request>
    <set_parameter>
        <module>MODULE_NAME</module>
        <module_number>MODULE_INDEX</module_number>
        <name>PARAM_NAME</name>
        <value>PARAM_VALUE</value>
    </set_parameter>
</request>

MODULE_NAME - the name of the module to modify (eg. Color_Filter) MODULE_INDEX - which module to modify in case you have more than one module of the same name (i.e. two Color_Filter modules). PARAM_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)

<response>ok</response>

Reading a module parameter

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

<request>
    <get_parameter>
        <module>MODULE_NAME</module>
        <module_number>MODULE_INDEX</module_number>
        <name>PARAM_NAME</name>
    </get_parameter>
</request>

MODULE_NAME - the name of the module to read (eg. Color_Filter) MODULE_INDEX - which module to read in case you have more than one module of the same name (i.e. two Color_Filter modules). PARAM_NAME - the parameter to read as seen in the XML string of the robofile (eg. min_distance)

<response>
    <PARAM_NAME>PARAM_VALUE</PARAM_NAME>
</response>

Inserting a module

This request allows you to insert a particular module in the pipeline. The module to insert is referred to by name. The tab and line number are optional as not all pipelines will contain more than one tab. When no line number is specified the module will be added to the end of the pipeline by default.

<request>
    <insert_module>
        <tab>TAB_NAME</tab>
        <line>LINE_NUMBER</line>
        <module>MODULE_NAME</module>
        <XYZ>xyz_value</XYZ>
    </insert_module>
</request>

TAB_NAME - the name of the tab to insert the module into
LINE_NUMBER - the line number in which to insert the module into
MODULE_NAME - the name of the module to delete (eg RGB_FILTER)
XYZ - depends on the configuration parameters of which module is being inserted.

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.

<request>
    <delete_module>
        <module>MODULE_NAME</module>
        <module_number>MODULE_NUMBER</module_number>
    </delete_module>
</request>

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

<response>ok</response>

Toggle disabling of a module

This request allows you to toggle if a particular module in the pipeline should be disabled or enabled. 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.

<request>
    <toggle_module>
        <module_name>MODULE_NAME</module_name>
        <module_number>MODULE_NUMBER</module_number>
    </toggle_module>
</request>

MODULE_NAME - the name of the module to toggle to disabled or enabled (eg RGB_FILTER) MODULE_NUMBER - which module to delete in case you have more than one module of the same name (i.e. two Color_Filter modules).

<response>ok</response>

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.

<request>
    <module_timer>
        <module_name>MODULE_NAME</module_name>
        <module_number>MODULE_NUMBER</module_number>
    </module_timer>
</request>

MODULE_NAME - the name of the module to toggle to query the running time (eg RGB_FILTER) MODULE_NUMBER - which module to query in case you have more than one module of the same name (i.e. two Color_Filter modules).

<response>
  <module_timer>
    <module>RGB_Filter</module>
  </module_timer>
</response>

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.

<request>
    <load_image>
        <filename>FILENAME</filename>
        <name>NAME</name>
    </load_image>
</request>

FILENAME - the image filename to load NAME - the name the image is identified as. Can be source, processed or a marker name.

<response>ok</response>

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.

<request>
    <save_image>
        <filename>FILENAME</filename>
        <name>NAME</name>
    </save_image>
</request>

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

<response>ok</response>

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.

<request>
    <set_camera>DRIVER_NAME</set_camera>
</request>

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

<response>ok</response>

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.

<request>
    <get_camera_list></get_camera_list>
</request>

<response>
  <get_camera_list>
  	<camera>Logitech QuickCam PTZ</camera>
  	<camera>Creative Notebook</camera>
 	</get_camera_list>
</response>

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.

<request>
    <get_camera></get_camera>
</request>

<response>
  <get_camera>Logitech QuickCam PTZ</get_camera>
</response>

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.

<request>
  <set_camera_format>
    <camera_index>INDEX</camera_index>
    <width>WIDTH</width>
    <height>HEIGHT</height>
    <frame_rate>FPS</frame_rate>
    <compression>COMPRESSION</compression>
  </set_camera_format>
</request>

INDEX - which camera to set (index is based on order of what is returned from get_camera)
WIDTH - the width of the image to capture (eg. 320)
HEIGHT - the height of the image to capture (eg. 240)
FPS - the number of frames per second to capture (eg. 30)
COMPRESSION - the data format used to transmit the image from the camera to the PC (eg. RGB or I420, etc)

<response>ok</response>

Getting the active camera's format

Returns the format settings for the current camera.

<request>
  <get_camera_format></get_camera_format>
  <camera_index>INDEX</camera_index>
</request>

INDEX - which camera to get (index is based on order of what is returned from get_camera)

<response>
    <camera_index>INDEX</camera_index>
  <width>320</width>
  <height>240</height>
  <frame_rate>30</frame_rate>
  <compression>RGB</compression>
</response>

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.

<request>
    <get_camera_dialogs></get_camera_dialogs>
</request>

<response>
  <get_camera_dialogs>
  	<dialog>Video Format</dialog>
  	<dialog>Video Capture</dialog>
 	</get_camera_dialogs>
</response>

Show camera dialog

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

<request>
    <show_camera_dialog></show_camera_dialog>
</request>

<response>ok</response>

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.

<request>
  <set_camera_properties>
    <brightness>
      <value>NUMBER_VALUE</value>
    </brightness>
    <contrast>
      <value>NUMBER_VALUE</value>
    </contrast>
    <gain>
      <value>NUMBER_VALUE</value>
      <auto>1 or 0</auto>
    </gain>
    <exposure>
      <value>NUMBER_VALUE</value>
      <auto>1 or 0</auto>
    </exposure>
    <sharpness>
      <value>NUMBER_VALUE</value>
    </sharpness>
    <saturation>
      <value>NUMBER_VALUE</value>
    </saturation>
    <hue>
      <value>NUMBER_VALUE</value>
    </hue>
    <zoom>
      <value>NUMBER_VALUE</value>
    </zoom>
    <iris>
      <value>NUMBER_VALUE</value>
      <auto>1 or 0</auto>
    </iris>
    <focus>
      <value>NUMBER_VALUE</value>
      <auto>1 or 0</auto>
    </focus>
    <gamma>
      <value>NUMBER_VALUE</value>
    </gamma>
    <pan>
      <value>NUMBER_VALUE</value>
    </pan>
    <tilt>
      <value>NUMBER_VALUE</value>
    </tilt>
    <roll>
      <value>NUMBER_VALUE</value>
    </roll>
    <whitebalance>
      <value>NUMBER_VALUE</value>
      <auto>1 or 0</auto>
    </whitebalance>
    <red>
      <value>NUMBER_VALUE</value>
    </red>
    <blue>
      <value>NUMBER_VALUE</value>
    </blue>
  </set_camera_properties>
</request>

NUMBER_VALUE - the value of the specific property that you want to set

<response>ok</response>

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.

<request>
  <get_camera_properties></get_camera_properties>
</request>

OR a combination of

<request>
  <get_camera_properties>
    <brightness></brightness>
    <contrast></contrast>
    <gain></gain>
    <exposure></exposure>
    <sharpness></sharpness>
    <saturation></saturation>
    <hue></hue>
    <zoom></zoom>
    <iris></iris>
    <focus></focus>
    <gamma></gamma>
    <pan></pan>
    <tilt></tilt>
    <roll></roll>
    <whitebalance></whitebalance>
    <red></red>
    <blue></blue>
  </get_camera_properties>
</request>

The response will contain several fields.
VALUE - the current value of the property
MIN - the minimum value the property can be set to
MAX - the maximum value the property can be set to
AUTO - the current setting of the automatic mode (if applicable)

<response>
  <brightness>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
  </brightness>
  <contrast>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
  </contrast>
  <gain>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
    <auto>1 or 0</auto>
  </gain>
  <exposure>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
    <auto>1 or 0</auto>
  </exposure>
  <sharpness>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
  </sharpness>
  <saturation>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
  </saturation>
  <hue>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
  </hue>
  <zoom>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
  </zoom>
  <iris>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
    <auto>1 or 0</auto>
  </iris>
  <focus>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
    <auto>1 or 0</auto>
  </focus>
  <gamma>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
  </gamma>
  <pan>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
  </pan>
  <tilt>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
  </tilt>
  <roll>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
  </roll>
  <whitebalance>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
    <auto>1 or 0</auto>
  </whitebalance>
  <red>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
  </red>
  <blue>
    <value>NUMBER_VALUE</value>
    <min>NUMBER_VALUE</min>
    <max>NUMBER_VALUE</max>
  </blue>
</response>

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.

<request>
    <run>MODE</run>
</request>

MODE - can be toggle, on, off, once, or a number of frames to process

<response>ok</response>

Pausing/Resuming 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.

<request>
    <pause></pause>
</request>

OR

<request>
    <resume></resume>
</request>

<response>ok</response>

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.

<request>
    <wait_variable>
        <name>VAR_NAME</name>
        <value>VAR_VALUE</value>
        <timeout>TIMEOUT</timeout>
    </wait_variable>
</request>

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

<response>ok</response>

OR

<response><error>Timeout exceeded</error></response>

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 wait_image 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.

<request>
    <wait_image>
        <timeout>TIMEOUT</timeout>
    </wait_image>
</request>

TIMEOUT - the maximum time to wait for a new image to be captured

<response>ok</response>

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.

<request>
  <interface>
    <command>edit</command>
    <module>MODULE_NAME</module>
    <module_number>MODULE_INDEX</module_number>
  </interface>
</request>

MODULE_NAME - the name of the module to modify (eg. Color_Filter or Canny or ...) MODULE_INDEX - which module to modify in case you have more than one module of the same name (i.e. two Color_Filter modules).

<response>ok</response>

Minimizing RoboRealm Interface

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

<request>
  <interface>
    <command>minimize</command>
  </interface>
</request>

<response>ok</response>

Maximizing RoboRealm Interface

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

<request>
  <interface>
    <command>maximize</command>
  </interface>
</request>

<response>ok</response>

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.

<request>
  <interface>
    <command>resize</command>
    <width>100</width>
    <height>100</height>
  </interface>
</request>

<response>ok</response>

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.

<request>
  <interface>
    <command>move</command>
    <x_position>100</x_position>
    <y_position>100</y_position>
  </interface>
</request>

<response>ok</response>

Moving and Resizing the RoboRealm Interface

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

<request>
  <interface>
    <command>position</command>
    <x_position>100</x_position>
    <y_position>100</y_position>
    <width>100</width>
    <height>100</height>
  </interface>
</request>

<response>ok</response>

Showing and Hiding the RoboRealm Interface

The following request will hide the RoboRealm interface

<request>
  <interface>
    <command>faceless</command>
  </interface>
</request>

<response>ok</response>

The following request will show the RoboRealm interface if hidden

<request>
  <interface>
    <command>display</command>
  </interface>
</request>

<response>ok</response>

Quitting RoboRealm API

The following request will terminate the current connection to RoboRealm API. 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.

<request>
    <quit></quit>
</request>

None

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.

<request>
    <version></version>
</request>

<response>2.0.6.1</response>

Closing RoboRealm

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.

<request>
    <close></close>
</request>

<response>ok</response>

Formatting note

Each request message can only process one command. For multiple commands you need to wrap each of them around a request tag. This is wrong:

<request>
    <set_variable>
        <name>VAR_NAME</name>
        <value>VAR_VALUE</value>
    </set_variable>
    <set_variable>
        <name>VAR_NAME_2</name>
        <value>VAR_VALUE_2</value>
    </set_variable>
</request>

while this is correct.

<request>
    <set_variable>
        <name>VAR_NAME</name>
        <value>VAR_VALUE</value>
    </set_variable>
</request>
<request>
    <set_variable>
        <name>VAR_NAME_2</name>
        <value>VAR_VALUE_2</value>
    </set_variable>
</request>

New Post

Related Forum Posts	Last post	Posts	Views
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	632
VBscript module Hi Roborealm Support, Inside my roborealm flow vision, I have added a vbscript program.	2 year	4	1196
how to download how to download roborealm...	3 year	1	1450
Calling a Tab through the API Hi Y'all How do I make a call to a Tab thru the API?...	3 year	1	1585
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	1640
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	1660
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...	4 year	3	3132
Is RR Idle Yet? I'm working in vb.net. I need to know when RR is Idle (done processing the pipeline)...	4 year	3	2523
SetImage Goodmorning, i'm working with RoboRealm and a linear Basler camera. W...	5 year	2	2559
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...	5 year	7	2968