Ontologenius Documentation

Ontologenius launchers

Ontologenius consists of two executables: the kernel and a graphical interface (ontoloGUI). While the first is mandatory, the only purpose of the latter is to quickly see the effect of queries.

Ontologenius core

An Ontologenius core needs at least three parameters to be able to run:

language: the language used by Ontologenius when dealing with names in natural language. It could be for example "en". This value can be modified during execution but must still be defined at launch.
intern_file: the OWL file that will be used to store the ontology of all the concepts present in Ontologenius when you stop it. If the file does not exist, it will be automatically created. If the file path does not exist, it will NOT be created. To don't use an internal file, you have to set this parameter to "none".
files: a set of OWL files that will be loaded at the launch of Ontologenius. If intern_file is set and already exists, these files will not be taken into account. Additionally, if the files import other files, the latter will be automatically loaded too.

Imported files can be Github URL, Gitlab URL, raw URL or local path. In all cases, Ontologenius will try to identify a ROS package in the paths and will use your local package if it exists.

parameters overview

Let's see what this file system means first when we use Ontologenius in single mode at first.

We consider the following parameters:

<launch>
  <arg name="language" default="en"/>
  <arg name="intern_file" default="$(find ontologenius)/file_intern/ontologenius.owl"/>
  <arg name="files" default="
    $(find ontologenius)/files/attribute.owl
    $(find ontologenius)/files/colors.owl
    $(find ontologenius)/files/positionProperty.owl
  "/>
  <node name="ontologenius_core" pkg="ontologenius" type="ontologenius_single" output="screen" args="-l $(arg language) -i $(arg intern_file) $(arg files)"> </node>
</launch>

import os
 
from ament_index_python import get_package_share_directory
 
from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument
from launch.substitutions import LaunchConfiguration
from launch.substitutions import TextSubstitution
from launch_ros.actions import Node
 
def generate_launch_description():
 
    language_arg = DeclareLaunchArgument(
        "language", default_value=TextSubstitution(text="en")
    )
    intern_file_arg = DeclareLaunchArgument(
        "intern_file", default_value=TextSubstitution(text=os.path.join(get_package_share_directory('ontologenius'), "file_intern/ontologenius.owl")) 
    )
    files_arg = DeclareLaunchArgument(
        "files", default_value=TextSubstitution(text=os.path.join(get_package_share_directory('ontologenius'), "files/attribute.owl") +  " " +
                                                     os.path.join(get_package_share_directory('ontologenius'), "files/colors.owl") +  " " +
                                                     os.path.join(get_package_share_directory('ontologenius'), "files/positionProperty.owl"))
    )
 
    ontologenius_core_node = Node(
            package='ontologenius',
            executable='ontologenius_single',
            name='ontologenius_core',
            output='screen',
            arguments=['-l', LaunchConfiguration('language'),
                       '-i', LaunchConfiguration('intern_file'),
                       LaunchConfiguration('files')]
    )
 
    return LaunchDescription([
        language_arg,
        intern_file_arg,
        files_arg,
        ontologenius_core_node
    ])

When you start Ontologenius for the first time with these parameters, you are in case a). This means that the internal file does not exist at the moment or is empty. In this case Ontologenius will load the four files listed in the file parameter.

Once you stop Ontologenius, the current knowledge will be saved in the internal file. So, when you run Ontologenius again, the internal file will exist and will not be empty this time. You will then be in case b) where the files listed will no longer be taken into account and only the internal file will be loaded.

All the ontologies listed in the files parameter can be considered as the basic knowledge of your agent and the internal file as his personal memory.

Now consider using Ontologenius in multi mode with the same parameters. The only difference here is the executable used.

<launch>
  <arg name="language" default="en"/>
  <arg name="intern_file" default="$(find ontologenius)/file_intern/ontologenius.owl"/>
  <arg name="files" default="
    $(find ontologenius)/files/attribute.owl
    $(find ontologenius)/files/colors.owl
    $(find ontologenius)/files/positionProperty.owl
  "/>
  <node name="ontologenius_core" pkg="ontologenius" type="ontologenius_multi" output="screen" args="-l $(arg language) -i $(arg intern_file) $(arg files)"> </node>
</launch>

import os
 
from ament_index_python import get_package_share_directory
 
from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument
from launch.substitutions import LaunchConfiguration
from launch.substitutions import TextSubstitution
from launch_ros.actions import Node
 
def generate_launch_description():
 
    language_arg = DeclareLaunchArgument(
        "language", default_value=TextSubstitution(text="en")
    )
    intern_file_arg = DeclareLaunchArgument(
        "intern_file", default_value=TextSubstitution(text=os.path.join(get_package_share_directory('ontologenius'), "file_intern/ontologenius.owl")) 
    )
    files_arg = DeclareLaunchArgument(
        "files", default_value=TextSubstitution(text=os.path.join(get_package_share_directory('ontologenius'), "files/attribute.owl") +  " " +
                                                     os.path.join(get_package_share_directory('ontologenius'), "files/colors.owl") +  " " +
                                                     os.path.join(get_package_share_directory('ontologenius'), "files/positionProperty.owl"))
    )
 
    ontologenius_core_node = Node(
            package='ontologenius',
            executable='ontologenius_multi',
            name='ontologenius_core',
            output='screen',
            arguments=['-l', LaunchConfiguration('language'),
                       '-i', LaunchConfiguration('intern_file'),
                       LaunchConfiguration('files')]
    )
 
    return LaunchDescription([
        language_arg,
        intern_file_arg,
        files_arg,
        ontologenius_core_node
    ])

Since you will be able to manage multiple agents, you will have several internal files. Taking the above parameters and creating two bob and max agents, Ontologenius will concide two internal files: ontologenius_bob.owl and ontologenius_max.owl

For the rest of the mechanism, it will work as in single mode. This means that the files listed can be considered the common ground of all agents. Every time a new agent is created, he will be charged with that common ground.

An Ontologenius core can take additional parameters for advanced uses:

config_file: the configuration file that will be used to configure the reasoners. To use the default configuration, you have to set this parameter to "none". See the configuration page to setup your file.
display: is a boolean ("true" or "false") to enable or disable the trees representing the content of the loaded files. By default this parameter is setted to true.
robot_file: a single OWL file that will be loaded at the launch of Ontologenius (only in multi mode) if the instance name contain the word "robot". If intern_file is set and already exists, this file will not be taken into account.
human_file: a single OWL file that will be loaded at the launch of Ontologenius (only in multi mode) if the instance name does not contain the word "robot". If intern_file is set and already exists, this file will not be taken into account.

Either for the robot file or the human file, Ontologenius will automatically load the related imported files if some exist.

Here below is an example of launch file using all the parameters.

<launch>
  <arg name="language" default="en"/>
  <arg name="intern_file" default="$(find ontologenius)/file_intern/ontologenius.owl"/>
  <arg name="config_file" default="$(find ontologenius)/configuration/config_example.yaml"/>
  <arg name="display" default="true"/>
  <arg name="robot_file" default="$(find ontologenius)/files/ontologenius_robot.owl"/>
  <arg name="human_file" default="$(find ontologenius)/files/ontologenius_human.owl"/>
  <arg name="files" default="
    $(find ontologenius)/files/attribute.owl
    $(find ontologenius)/files/colors.owl
    $(find ontologenius)/files/positionProperty.owl
  "/>
  <node name="ontologenius_core" pkg="ontologenius" type="ontologenius_multi" output="screen" args="-l $(arg language) -c $(arg config_file) -i $(arg intern_file) -d $(arg display) -r $(arg robot_file) -h $(arg human_file) $(arg files)"> </node>
</launch>

import os
 
from ament_index_python import get_package_share_directory
 
from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument
from launch.substitutions import LaunchConfiguration
from launch.substitutions import TextSubstitution
from launch_ros.actions import Node
 
def generate_launch_description():
 
    language_arg = DeclareLaunchArgument(
        "language", default_value=TextSubstitution(text="en")
    )
    intern_file_arg = DeclareLaunchArgument(
        "intern_file", default_value=TextSubstitution(text=os.path.join(get_package_share_directory('ontologenius'), "file_intern/ontologenius.owl")) 
    )
    config_file_arg = DeclareLaunchArgument(
        "config_file", default_value=TextSubstitution(text=os.path.join(get_package_share_directory('ontologenius'), "configuration/config_example.yaml")) 
    )
    display_arg = DeclareLaunchArgument(
        "display", default_value=TextSubstitution(text="true") 
    )
    robot_file_arg = DeclareLaunchArgument(
        "robot_file", default_value=TextSubstitution(text=os.path.join(get_package_share_directory('ontologenius'), "files/ontologenius_robot.owl")) 
    )
    human_file_arg = DeclareLaunchArgument(
        "human_file", default_value=TextSubstitution(text=os.path.join(get_package_share_directory('ontologenius'), "files/ontologenius_human.owl")) 
    )
    files_arg = DeclareLaunchArgument(
        "files", default_value=TextSubstitution(text=os.path.join(get_package_share_directory('ontologenius'), "files/attribute.owl") +  " " +
                                                     os.path.join(get_package_share_directory('ontologenius'), "files/colors.owl") +  " " +
                                                     os.path.join(get_package_share_directory('ontologenius'), "files/positionProperty.owl"))
    )
 
    ontologenius_core_node = Node(
            package='ontologenius',
            executable='ontologenius_multi',
            name='ontologenius_core',
            output='screen',
            arguments=['-l', LaunchConfiguration('language'),
                       '-i', LaunchConfiguration('intern_file'),
                       '-c', LaunchConfiguration('config_file'),
                       '-d', LaunchConfiguration('display'),
                       '-r', LaunchConfiguration('robot_file'),
                       '-h', LaunchConfiguration('human_file'),
                       LaunchConfiguration('files')]
    )
 
    return LaunchDescription([
        language_arg,
        intern_file_arg,
        config_file_arg,
        display_arg,
        robot_file_arg,
        human_file_arg,
        files_arg,
        ontologenius_core_node
    ])

Arguments are passed to the executable as options (-l, -i, -c). If you do not set an option, the setting will take a default value.

OntoloGUI

OntoloGUI is the Ontologenius GUI. Its only purpose is to help you develop applications using Ontologenius. It is not necessarily necessary to launch it and is presented in more detail here.

  <node name="ontologenius_gui" pkg="ontologenius" type="ontoloGUI" output="screen"> </node>

Launch files

Several launch files are already available to you and could be overload to change the default parameters. All launch files are available in XML for ROS1 and ROS2 as well as Yaml and Python for ROS2.

ontologenius_empty : ontologenius_core(single)
ontologenius_full : ontologenius_core(single) & ontologenius_gui
ontologenius_multi_empty : ontologenius_core(multi)
ontologenius_multi_full : ontologenius_core(multi) & ontologenius_gui
ontologenius : ontologenius_core(single)

Advanced use for ROS1

All launch files have an additional argument called tcmalloc_path which is used to locally set the LD_PRELOAD env variable in order to use custom allocators. If you prefer other allocator than tcmalloc (like jemalloc) tou can use the same argument.

Ontologenius Documentation

Getting Start

Overview

All C++ Classes

All Python Classes

Ontologenius launchers

Ontologenius core

OntoloGUI

Launch files

Advanced use for ROS1