Contents
SRS OBJECT DATABASE
The package srs_object_database allow storing information about an object in a database postgresql. It provides also service to insert, update and retrieve this information.
Installing and Configuring Database
Data about objects, such as: mesh,grasp,surface points, images, is stored in file inside a file repository while the database keep track, for each object, of the data files associated with it.
Postgresql Database
The first step is to install postgresql database. General information on how to install and configure the database are described in Installing a PostgreSQL Server.
Database Creation
After the previous step is completed an empty database must be created using a script found inside the folder db_scripts of the package srs_object_database. The first time you need to create an empty database with the internal structure and data. To do this simply enter the db_scripts folder and run:
. createDatabase.sh databaseName
NOTE: database name must not include capital letters.
This will create an empty database named databaseName. You can usethis script also to create additional database in case you want to do some test. Also if you want to create an empty database you can use the following script:
. createemptyDb.sh databaseName
In general if you have already a user which is different from 'willow' and database should be assigned to this user, you can specify an additional parameter which is the name of the sql user to be used to create database. This second command can be used in all previous scripts and the one used to restore and delete database. For example to create a database with owner the user 'srs_user', which must be already created before executing the script.
. createemptyDb.sh databaseName srs_user
Database Restore
Database can be restored to original data using the following script:
. resetDatabase.sh databaseName
PS: warning this command will drop the previous database so your data will be lost!
Database Delete
Database can be deleted completely in some case:
. deleteDatabase.sh databaseName
PS: warning this command will drop the previous database so your data will be lost!
File repository
After the database creation is required to create the fileRepository which can be retrieved in the git repository git file share repository. This share contains a root folder named ros_data_files Upload the laters version of the repository that will be syncronized with the latest data created by the script in the folder db_scripts.
Configuration of SRS object services
Environment configuration is passed to services through the launch file which run srs_object_database services. The file called srs_db.launch is stored in the folder launch of the srs_object_database.
<launch> <param name="instanceName" value="localhost" type="str"/> <param name="dbPort" value="5432" type="str"/> <param name="databaseName" value="srs_template_database" type="str" /> <param name="userName" value="user" type="str" /> <param name="pwd" value="pwd" type="str" /> <param name="repoPath" value="/path_to_ros_fileshare/ros_data_files/" type="str"/> <node pkg="srs_object_database" name="get_model_server" type="get_model_server" output="screen"/> <node pkg="srs_object_database" name="get_model_mesh" type="get_model_mesh" output="screen"/> <node pkg="srs_object_database" name="get_model_surf" type="get_model_surf" output="screen"/> <node pkg="srs_object_database" name="get_model_urdf" type="get_model_urdf" output="screen"/> <node pkg="srs_object_database" name="get_model_pcl" type="get_model_pcl" output="screen"/> <node pkg="srs_object_database" name="get_model_grasp" type="get_model_grasp" output="screen"/> <node pkg="srs_object_database" name="get_model_img" type="get_model_img" output="screen"/> <node pkg="srs_object_database" name="insert_object_service" type="insert_object_service" output="screen"/> <node pkg="srs_object_database" name="dispacherService" type="dispacherService" output="screen" /> </launch>
The configuration is controlled by the param element inside the launch file.
Localhost set the ip addres of the postgreSQL server. For local installation use 'localhost'.
<param name="instanceName" value="localhost" type="str"/>
dbPort set the port on which the database server is listening. Default for postgres is 5432
<param name="dbPort" value="5432" type="str"/>
databaseName must be set to the name of database created before.
<param name="databaseName" value="srs_template_database" type="str" />
username must be set to the user which own read and write right on the srs_database.
<param name="userName" value="user" type="str" />
pwd must provide the password for the user specified at the previous point.
<param name="pwd" value="willow" type="str" />
repoPath is used to set the root folder where the file repository is stored. Note that at the end / is added otherwise services will fail to return object data.
<param name="repoPath" value="/path_to_ros_fileshare/ros_data_files/" type="str"/>
Once this parameters are correctly configured the services provided by srs_object_database are ready to be run.
example_node_name
Example description what the node is doing.Services
insert_object_service (srs_object_database/InsertObject)- Search service used to insert and update object information on database
- This service allows to retrieve data about objects
- Search service used to search object id from database.
- Search service used to search mesh for a given list of object.
- Search service used to search image for a given list of object.
- Search service used to search point cloud for a given list of object.
- Search service used to search grasp data for a given list of object.
- Search service used to search surface descriptor for a given list of object.
- Search service used to search urdf data for a given list of object.
Usage/Examples
In order to run all ros services for both insert and retrieval execut the launch file.
roslaunch srs_object_database srs_db.launch
clientTest
A simple client has been created to allow inserting and updating information on database. This service make use of service provided by srs_object_database and should be used only for the purpose of testing data. It is executed with rosrun. Is mandatory to execute the srs_object_database launch file to start all services before running the client.
rosrun srs_object_database clientTest params
After running the client it will be possible to specify an action to take:
Choose between [i]nsert,[u]pdate,[r]etrieve functionality
The selection of the action should be consequence of the input parameters.
how to search data with clientTest
clientTest can be used to retrieve data. To achieve this provide parameters as specified in this section and use r to specify that you want to retrieve data. The client calls the srs_object_database/GetObjecId service and by command line is possible to search in database for object id using the following combination of input:
Search all objects:
Providing all as parameter allows retrieve all object currently stored in the sql database.
rosrun srs_object_database clientTest all
Search by object id:
It is possible to specify id as key search and provide a numeric object id to verify if an object with a give id is present in database and in case retrieve its infomation.
rosrun srs_object_database clientTest id object_id
Search by object category: It is possible to search all object which have a specified class. Use class as first parameter and provide an object_class such as glass.
rosrun srs_object_database clientTest class object_class
Search by object name: It is possible to search a specific object using its name. Use nameas first parameter and provide an object_name such as "milkBox1".
rosrun srs_object_database clientTest class object_name
how to force retrieve of data with clientTest without user interaction
Adding the key 'retrieve' after the previous command will allow the client to direclty retrieve object data, the general data, without requiring additional user interaction.
rosrun srs_object_database clientTest testInputInsert.txt update
how to retrieve data with clientTest
after an object as been retrieved the clienTest allow to return the data using the command line:
[ INFO] [1321287335.121522116]: Retrieved 0 [ INFO] [1321287335.121909683]: Enter number of menu option you wish: [ INFO] [1321287335.122290084]: 1 Mesh [ INFO] [1321287335.122558812]: 2 Point Cloud [ INFO] [1321287335.122709195]: 3 Image [ INFO] [1321287335.123171475]: 4 Grasp [ INFO] [1321287335.123527822]: 5 Feature Points [ INFO] [1321287335.124457739]: 6 Urdf [ INFO] [1321287335.124734287]: 7 List selected objects id - tag - description - size [ INFO] [1321287335.125110589]: 0 Exit
Selecting 3, for example, will allow to retrieve, if available, image of the current object retrieved by the search.
how to insert data with clientTest
Inserting new object is usefull to test functionality of other components which make use of database. clientTest provide such functionality in order to allow developer to test object information and services. A file with a list of property for a give object is provided and then the client retrieve the files with its data and load them in an appropriate way to be sent to InsertObject service.
The input file must be stored inside the Input folder available in the git repository git file share repository with the data files. The input file is
id name category description x-size y-size z-size basic-shape graspable urdf image grasp mesh typeMesh pcl surf end
Each attribute will be insert in database in the respective table. For object such as: urdf,image,grasp,mesh,pcl or surf. It mush be provided the filename, with extenstion, of the file containing the data to be inserted. This file must be placed in the Input folder inside the file repository. Once the data will be inserted, a file will be created inside the appropiate folder of the file repository. One example is testInputInsert.txt which allow to insert a new object simply calling the clientTest:
rosrun srs_object_database clientTest testInputInsert.txt
In the output you will be able to see which id is assigned to this new object.
how to force insertion of data with clientTest without user interaction
Adding the key 'insert' after the previous command will allow the client to direclty insert object and its data without requiring additional user interaction.
rosrun srs_object_database clientTest testInputInsert.txt insert
how to update data with clientTest
Updating an object with the client work in the same way as the insert, the only difference is that when providing an input file you will change information so that the service will repleace old information with the new information or will insert additional information that previouvsly where not provided. It is mandatort that in the input file the id will not be empty, otherwise it will be interpreted as an insert, but you will provide the id of the object to be updated.
how to force update of data with clientTest without user interaction
Adding the key 'update' after the previous command will allow the client to direclty update object and its data without requiring additional user interaction.
rosrun srs_object_database clientTest testInputInsert.txt update
general usage of srs_object_database services
The clienTest which is used for test purpose, build request for srs_object_database services. In run time scenario those are the services that other components should invoke.
Inserting/Updating Objects
To insert and update object data the service "InsertObject" should be used. Note that you should provide a type of mesh (usually iv.txt) and an Image type such as: icon,top-view,front-view.
# insert create a new object # update update replacing old data or adding missing data # the model id provide it only in case you want to update an already existing object int32 model_id ... # data inserted by service must be serialized in case of uint8 uint8[] pcl uint8[] fpt sensor_msgs/Image img string image_type uint8[] data_grasp #mesh data and type extension ex dae, iv.txt uint8[] data_mesh string meshType uint8[] urdf --- # is/ids of objects inserted usefull to know which id the service has associated to # a new objet int32 model_id
Getting Objects data
To retrieve data a dispacher service can be invoked. It has some boolean flag which must be put to 1 to indicate the data that should be retrieved if available for the provided objects ids.
... bool mesh bool pcl bool surf bool image bool grasp bool urdf ...
Getting objects id of objects
In order to get objects ids the getObjectId service must be invoked. It requires a type parameters which specify the search criteria as well as an item which is the value of the key provided for the search. It can be specified as type: all, to retrieve all objects id in database, name, to search a specific object based on its name, class, to search ids of object using their class.
# retrieves the object id for a class of items # type of search. use item if want to search on item description such as glass # use id if want to search data about a specific object and you know its id string type # the search key, could be an object description such as glass or an id i.e. 10000 string item ---
This service will return general information for the objects retrieved, such as name, description, size.
Calling a specific service
While using getData allow to retrieve more information at the same time, if the object id is know and only a specific service need to be called it is possible to just call the respective service. For instance if it is required to get only image information for a give object id, the service getImg can be directly called. In this specific case calling directly this service allow to use additional parameter such as the type of the image to be retrieved for the object id provided in the request message. It works like a filter to select, for instance, only icon image.
# retrieves the object id for a class of items # is/ids of objects of which we will retrieve information int32[] model_ids # apply a filter on the search to get only a subset of image # all or icon or top-view string type --- # the outcome of the end service string return_response # array of message containing image information retrieved srs_object_database/img[] msg
Managing object category
The database allow management of knowledge category associated to an object. The category could be managed through services or clientTest with the following command line:
rosrun srs_object_database clientTest category
The key 'category' tells the client to enter a submenu where it is possible to query database for the existing category, insert new category, search category associated with an object.
