Best practices

This page is to outline some best practices that have been developed while working with the KnowRob system. It is recommended to follow these guidelines to ensure interoperability and facilitate scaling to larger installations.

KnowRob packages may contain both code (i.e. Prolog and Java programs) and data (i.e. OWL files). In many cases, the code can be kept rather generic (e.g. methods for reading objects in a map), while the data is inherently specific to the use case at hand. To allow flexible re-use of the system in different settings, try to minimize the amount of data that is auto-loaded when a package is launched. For example, do not auto-load environment maps in the init.pl file, but use a launch file such as the ones in knowrob_map_data to load the file at startup. Otherwise, people that work in a different scenario (e.g. outdoor robotics) will not be able to use your package.

Though some old OWL files still contain them, avoid the use of simple instance names such as 'Cup1', 'Refrigerator67', or 'RotationMatrix3D11'. While they work fine in small scenarios, they may lead to nasty and hard-to-find bugs: If for instance two maps are loaded that contain objects (or matrices) with the same name, queries will return both the results from the first and the second map in arbitrary order. If you use only the first result, this may cause the refrigerator to have the width specified in map 1, the depth from map 2, and the height from map 1.

Instead, use the rdf_instance_from_class predicate in the knowrob_owl.pl module in knowrob_common package that creates more unique identifiers by appending a suffix of eight random characters.

Especially when combining several packages for a demonstration, it may be tempting to add dependencies to a package that are needed in this particular use case. For example, this use case will always show a particular map in a visualization, and it may seem convenient to auto-load that map whenever the visualization is started.

This practice quickly leads to clogged dependency lists that load packages that are only needed in some use cases, but may cause problems in others. Instead, create specific packages for each demo use case that (usually) only consist of launch files, dependencies and an init.pl file that initializes KnowRob. This will make it easy to start KnowRob for your use case, but will not cause problems for anyone else.

To build up documentation while developing a package, it proved useful to simply copy/paste the test queries used for development to a wiki page. Ideally, they should contain all steps needed from a bash shell to a working environment and should be executable one after the other without having to think too much. From our experience, creating this documentation is very little overhead at development time, when these queries and the values to be used are all well-known, while remembering how to use the code and reconstructing the queries later on is often much more difficult.