com.ur.urcap.api.domain.feature

Interface FeatureContributionModel

public interface FeatureContributionModel

This interface provides functionality for adding, updating and removing features in PolyScope.

Note: This interface must only be used in an installation contribution.

Since:

1.9.0

Method Summary

Modifier and Type	Method and Description
Feature	addFeature(String idKey, String suggestedName, Pose pose) Add a feature to the current PolyScope installation.
Feature	getFeature(String idKey) Returns the feature previously added by this URCap using the same idKey identifier.
void	removeFeature(String idKey) Remove a feature added by this URCap from PolyScope.
void	updateFeature(String idKey, Pose newPose) Update the pose of an existing feature added by this URCap.

Method Detail

addFeature

Feature addFeature(String idKey,
                   String suggestedName,
                   Pose pose)

Add a feature to the current PolyScope installation.

This makes the feature selectable by the end user as well as available to other URCap contributions (through the FeatureModel interface). The feature is not modifiable by the end user or other URCaps.

Parameters:

idKey - The key to identify this feature by, not null nor an empty string. The key is for this URCap only, i.e. it only has to be unique for this URCap and not "globally" for other URCaps.

suggestedName - Suggested name for the feature, not null nor an empty string. Valid names must match regex [a-zA-Z][a-zA-Z0-9_]{0,14} for a total of 15 characters. The final name can be retrieved from the returned feature instance.

pose - The pose of the feature with respect to the robot base, not null.

Returns:

The feature created and registered in PolyScope.

Throws:

FeatureAlreadyAddedException - If a feature has previously been added using the same idKey identifier. Use getFeature(String) to check if the feature has already been added to the current installation. Use updateFeature(String, Pose) to update the feature.

IllegalFeatureNameException - If the suggested name does not match required regex.

getFeature

Feature getFeature(String idKey)

Returns the feature previously added by this URCap using the same idKey identifier. Use this to verify if the feature is present in the current installation.

Parameters:

idKey - The key to identify this feature by, not null nor an empty string.

Returns:

The feature previously added by this URCap. Returns null if no feature exists in the current installation (with the specified idKey identifier).

updateFeature

void updateFeature(String idKey,
                   Pose newPose)

Update the pose of an existing feature added by this URCap.

Parameters:

idKey - The key to identify the feature, not null nor an empty string. A feature must have been added using the same key prior to calling this method.

newPose - The new pose to set for the feature with respect to the robot base, not null.

Throws:

FeatureNotFoundException - If no feature exists with the provided idKey identifier in the current installation.

removeFeature

void removeFeature(String idKey)

Remove a feature added by this URCap from PolyScope. Program nodes using the feature will be become undefined because the feature is no longer resolvable.

Parameters:

idKey - The identifier key used to add the feature with, not null nor an empty string.

Throws:

FeatureNotFoundException - If no feature exists with the provided idKey identifier in the current installation.