kaos.spatial
Class SpatialReasoner

java.lang.Object
  kaos.spatial.SpatialReasoner

All Implemented Interfaces:

SpatialDatabase, SpatialQuery

public class SpatialReasoner
extends java.lang.Object
implements SpatialDatabase, SpatialQuery

This class implements interfaces:

See Also:

SpatialDatabase, SpatialQuery

Field Summary

protected java.util.Vector	knownBasicRelations
protected java.util.Vector	knownReferencedRelations

Constructor Summary

protected

SpatialReasoner() Default constructor

Method Summary

void	deregisterSpatialObject(java.lang.String objectID) Deregister object identified by the given objectID and its spatial properties in the SpatialReasoner.
java.util.Vector<Location3D>	findLocationReferencedBy(java.lang.String relationName, java.lang.String subjectObjectID, java.lang.String referenceObjectID, double distance) This method returns a location of the subject object which is in the given relation with the reference object
java.util.Vector	findObjectsInRelation(java.util.Vector relationNames, java.lang.String subjectObjectID, float maxDistance) This method returns a vector of the IDs of objects being in the specified relation to the subject object, but in the specified maximum distance.
java.util.Vector	findObjectsInRelationReferencedBy(java.util.Vector relationNames, java.lang.String subjectObjectID, java.lang.String referenceObjectID, float maxDistance) This method returns objects being in the specified relations to the subject object in regards to the referenced object, but in the specified maximum distance.
java.util.Vector	findSpatialRelationsBetween(java.lang.String subjectObjectID, java.lang.String relatedObjectID) This method returns spatial relations between two objects from the perspective of the first subject object.
java.util.Vector	findSpatialRelationsReferencedBy(java.lang.String subjectObjectID, java.lang.String relatedObjectID, java.lang.String referencedObjectID) This method returns spatial relations between two objects from the perspective of the first subject object in regards to the reference object.
java.util.Vector<Location3D>	findSpecificSideOfObject(java.lang.String objectID, java.lang.String sideOrientation) This method finds the alternative name of the spatial object.
java.util.Vector	findUsingAlternativeName(java.lang.String objectAlternativeName) This method finds the spatial objects with the given alternative name
java.util.Vector<SpatialObject>	getAllSpatialObjects() This method allows to obtain a vector of all registered spatial object.
java.util.Vector	getAlternativeNames(java.lang.String objectID) This method get the alternative names of the spatial object.
java.util.Vector<Location3D>	getBoundingPoints(java.lang.String objectID) This method allows to obtain a vector of locations of the corners of the area bounding the object.
double	getDistanceBetween(java.lang.String subjectObjectID, java.lang.String relatedObjectID) This method returns a value of the distance between two objects
static SpatialReasoner	getInstance(java.lang.String transportName, boolean central) Retrieve an instance of SpatialReasoner.
Location3D	getObjectLocation(java.lang.String objectID) This method allows to obtain location of a known spatial object.
java.util.Set	getObjectOntologicalTypes(java.lang.String objectID) This method allows to obtain location of a known spatial object.
Orientation3D	getObjectOrientation(java.lang.String objectID) This method allows to obtain orientation of a known spatial object.
Block3D	getOccupiedSpace(java.lang.String objectID) This method allows to obtain aproximation of the occupied space of a known spatial object.
SpatialObject	getSpatialObject(java.lang.String objectID) This method allows to obtain spatial object.
double	getValueOfOrientationRelation(java.lang.String relationName, java.lang.String subjectObjectID, java.lang.String relatedObjectID) This method returns a value of rotation, in radius, requqired to directly face the given object being in the given initial spatial relation It is important to remember that this value is calculated based on the orientation and location associated with the subject object.
protected void	initVars()
void	registerSpatialObject(java.lang.String objectID, java.util.Set objectOntologyTypes, Location3D objectLocation, Orientation3D objectOrientation, Block3D objectOccupedSpace) This method allows to add information about a new spatial object.
void	registerSpatialObject(java.lang.String objectID, java.util.Set objectOntologyType, Orientation3D objectOrientation, java.util.Vector<Location3D> boundingPoints) This method allows to add information about a new spatial object.
void	setAlternativeName(java.lang.String objectID, java.lang.String objectAlternativeName) This method set the alternative name of the spatial object.
boolean	testSpatialRelationBetween(java.lang.String relationName, java.lang.String subjectObjectID, java.lang.String relatedObjectID) This method tests the given spatial relation between two objects from the perspective of the subject object.
boolean	testSpatialRelationsReferencedBy(java.lang.String relationName, java.lang.String relatedObjectID, java.lang.String subjectObjectID, java.lang.String referencedObjectID) This method test spatial relation between two objects from the perspective of the subject object in regards to the referenced object.
void	updateSpatialObject(java.lang.String objectID, Location3D objectLocation, Orientation3D objectOrientation, Block3D objectOccupedSpace) This method allows to modify information about a known spatial object.
void	updateSpatialObject(java.lang.String objectID, Orientation3D objectOrientation, java.util.Vector<Location3D> boundingPoints) This method allows to modify information about a known spatial object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

knownBasicRelations

protected java.util.Vector knownBasicRelations

knownReferencedRelations

protected java.util.Vector knownReferencedRelations

Constructor Detail

SpatialReasoner

protected SpatialReasoner()

Default constructor

Method Detail

getInstance

public static SpatialReasoner getInstance(java.lang.String transportName,
                                          boolean central)
                                   throws java.lang.Exception

Retrieve an instance of SpatialReasoner.

Returns:

a singleton, SpatialReasoner.

Throws:

java.lang.Exception

findObjectsInRelation

public java.util.Vector findObjectsInRelation(java.util.Vector relationNames,
                                              java.lang.String subjectObjectID,
                                              float maxDistance)
                                       throws NotRegisteredException,
                                              UnknownConceptException

Description copied from interface: SpatialQuery

This method returns a vector of the IDs of objects being in the specified relation to the subject object, but in the specified maximum distance. For instance, it can return: All the object being on the left and up to the subject, but not further then 20 meters or All the object in the subject space (teh subject depicts some block of space). It is important to remember that these relations are calculated based on the orientation and location associated with the subject object.

Specified by:

findObjectsInRelation in interface SpatialQuery

Parameters:

relationNames - - URIs in the OWL ontology file(s) to the relation definition, for instance left, down, etc.

subjectObjectID - - id of the subject object

maxDistance - - meximum distance of the search

Returns:

Vector - containing ids of the found objects

Throws:

NotRegisteredException - when the subject is not registered in the spatial database

UnknownConceptException - when the spatial relation is unknown

findObjectsInRelationReferencedBy

public java.util.Vector findObjectsInRelationReferencedBy(java.util.Vector relationNames,
                                                          java.lang.String subjectObjectID,
                                                          java.lang.String referenceObjectID,
                                                          float maxDistance)
                                                   throws NotRegisteredException,
                                                          UnknownConceptException

Description copied from interface: SpatialQuery

This method returns objects being in the specified relations to the subject object in regards to the referenced object, but in the specified maximum distance. For instance, it can return: All the object beign further-left and less-up to the subject than the referenced object, but not further then 20 meters. It is important to remember that these relations are calculated based on the orientation and location associated with the subject object.

Specified by:

findObjectsInRelationReferencedBy in interface SpatialQuery

Parameters:

relationNames - - URIs in the OWL ontology file(s) to the relation definition, for instance further-left, less-down, etc.

subjectObjectID - - id of the subject object

maxDistance - - maximum distance of the search

Returns:

Vector - containing ids of the found objects

Throws:

NotRegisteredException - when the objects are not registered in spatial database

UnknownConceptException - when the spatial relation is unknown

findSpatialRelationsBetween

public java.util.Vector findSpatialRelationsBetween(java.lang.String subjectObjectID,
                                                    java.lang.String relatedObjectID)
                                             throws NotRegisteredException

Description copied from interface: SpatialQuery

This method returns spatial relations between two objects from the perspective of the first subject object. For instance it can find: That in relation to the subject the related object is on the right and down. It is important to remember that these relations are calculated based on the orientation and location associated with the subject object.

Specified by:

findSpatialRelationsBetween in interface SpatialQuery

Parameters:

subjectObjectID - - id of the subject object

relatedObjectID - - id of the related object

Returns:

Vector - containing found relations URI in the OWL ontology file(s) to the relations defitions (the object, for instance, can be in the up and on the left relations)

Throws:

NotRegisteredException - when the objects are not registered in spatial database

findSpatialRelationsReferencedBy

public java.util.Vector findSpatialRelationsReferencedBy(java.lang.String subjectObjectID,
                                                         java.lang.String relatedObjectID,
                                                         java.lang.String referencedObjectID)
                                                  throws NotRegisteredException

Description copied from interface: SpatialQuery

This method returns spatial relations between two objects from the perspective of the first subject object in regards to the reference object. For instance it can find: That in relation to the subject the related object is further-right and less-down than the referenced object or that it is further than the referenced object. It is important to remember that these relations are calculated based on the orientation and location associated with the subject object.

Specified by:

findSpatialRelationsReferencedBy in interface SpatialQuery

Parameters:

subjectObjectID - - id of the subject object

relatedObjectID - - id of the related object

referencedObjectID - - id of the reference object

Returns:

Vector - containing found relations URI in OWL ontology (the objects can be, for instance, further-up and less-left relations)

Throws:

NotRegisteredException - when the objects are not registered in the spatial database

findSpecificSideOfObject

public java.util.Vector<Location3D> findSpecificSideOfObject(java.lang.String objectID,
                                                             java.lang.String sideOrientation)
                                                      throws NotRegisteredException

Description copied from interface: SpatialQuery

This method finds the alternative name of the spatial object.

Specified by:

findSpecificSideOfObject in interface SpatialQuery

Parameters:

objectID - - id of the object

sideOrientation - - the orientation of the searched side return Vector - vector containg locations of the ends of the found side

Throws:

NotRegisteredException - when the object is not registered in the spatial database

findLocationReferencedBy

public java.util.Vector<Location3D> findLocationReferencedBy(java.lang.String relationName,
                                                             java.lang.String subjectObjectID,
                                                             java.lang.String referenceObjectID,
                                                             double distance)
                                                      throws NotRegisteredException,
                                                             UnknownConceptException

Description copied from interface: SpatialQuery

This method returns a location of the subject object which is in the given relation with the reference object

Specified by:

findLocationReferencedBy in interface SpatialQuery

Parameters:

relationName - - URI of relation definition, for instance left, behind, etc.

subjectObjectID - - id of the subject object

distance - - the distance of the object outside

Returns:

Vector - containing location on the found side of the object (midpoint), the norma wector (as the second location) and the point outside the object in the given distance (as the third location)

Throws:

NotRegisteredException - when the objects are not registered in spatial database

UnknownConceptException - when the spatial relation is unknown

testSpatialRelationBetween

public boolean testSpatialRelationBetween(java.lang.String relationName,
                                          java.lang.String subjectObjectID,
                                          java.lang.String relatedObjectID)
                                   throws NotRegisteredException,
                                          UnknownConceptException

Description copied from interface: SpatialQuery

This method tests the given spatial relation between two objects from the perspective of the subject object. For instance it can test If the related object is on the left to the subject. It is important to remember that these relations are calculated based on the orientation and location associated with the subject object.

Specified by:

testSpatialRelationBetween in interface SpatialQuery

Parameters:

relationName - - URI in the OWL ontology file to the relation definition to be tested, for instance: inside, on-the-left, etc.

subjectObjectID - - id of the subject object

relatedObjectID - - id of the related object

Returns:

true - if the objects are in the tested relation

Throws:

NotRegisteredException - when the objects are not registered in spatial database

UnknownConceptException - when the spatial relation is unknown

testSpatialRelationsReferencedBy

public boolean testSpatialRelationsReferencedBy(java.lang.String relationName,
                                                java.lang.String relatedObjectID,
                                                java.lang.String subjectObjectID,
                                                java.lang.String referencedObjectID)
                                         throws NotRegisteredException,
                                                UnknownConceptException

Description copied from interface: SpatialQuery

This method test spatial relation between two objects from the perspective of the subject object in regards to the referenced object. For instance it can test: If the related object is further-left to the subject than the referenced object, or if it is simple further than the referenced object. It is important to remember that these relations are calculated based on the orientation and location associated with the subject object.

Specified by:

testSpatialRelationsReferencedBy in interface SpatialQuery

Parameters:

relationName - - URI in the OWL ontology file to the relation definition to be tested, for instance further-left, less-down, etc.

relatedObjectID - - id of the related object

subjectObjectID - - id of the subject object

referencedObjectID - - id of the referenced object

Returns:

true - if the objects are in the tested relations

Throws:

NotRegisteredException - when the objects are not registered in spatial database

UnknownConceptException - when the spatial relation is unknown

getValueOfOrientationRelation

public double getValueOfOrientationRelation(java.lang.String relationName,
                                            java.lang.String subjectObjectID,
                                            java.lang.String relatedObjectID)
                                     throws NotRegisteredException,
                                            UnknownConceptException,
                                            UnsatisfiedOrientationRelation

Description copied from interface: SpatialQuery

This method returns a value of rotation, in radius, requqired to directly face the given object being in the given initial spatial relation It is important to remember that this value is calculated based on the orientation and location associated with the subject object.

Specified by:

getValueOfOrientationRelation in interface SpatialQuery

Parameters:

relationName - - URI in the OWL ontology file to the relation definition, for instance left, down, etc.

subjectObjectID - - id of the subject object

relatedObjectID - - id of the related object

Returns:

double - represents an angle of orientation difference in radians

Throws:

NotRegisteredException - when the subject is not registered in the spatial database

UnknownConceptException - when the spatial relation is unknown

UnsatisfiedOrientationRelation

getDistanceBetween

public double getDistanceBetween(java.lang.String subjectObjectID,
                                 java.lang.String relatedObjectID)
                          throws NotRegisteredException

Description copied from interface: SpatialQuery

This method returns a value of the distance between two objects

Specified by:

getDistanceBetween in interface SpatialQuery

Parameters:

subjectObjectID - - id of the subject object

relatedObjectID - - id of the related object

Returns:

double - represents an angle of orientation difference in radians

Throws:

NotRegisteredException - when the subject is not registered in the spatial database

getAllSpatialObjects

public java.util.Vector<SpatialObject> getAllSpatialObjects()

Description copied from interface: SpatialDatabase

This method allows to obtain a vector of all registered spatial object.

Specified by:

getAllSpatialObjects in interface SpatialDatabase

Returns:

Vector - spatial oject with the given id

getSpatialObject

public SpatialObject getSpatialObject(java.lang.String objectID)
                               throws NotRegisteredException

Description copied from interface: SpatialDatabase

This method allows to obtain spatial object.

Specified by:

getSpatialObject in interface SpatialDatabase

Parameters:

objectID - - id of the object

Returns:

SpatialObject - spatial oject with the given id

Throws:

NotRegisteredException - when the object is not registered in the spatial database

getObjectOntologicalTypes

public java.util.Set getObjectOntologicalTypes(java.lang.String objectID)
                                        throws NotRegisteredException

Description copied from interface: SpatialDatabase

This method allows to obtain location of a known spatial object.

Specified by:

getObjectOntologicalTypes in interface SpatialDatabase

Parameters:

objectID - - id of the object

Returns:

Set - set of strings reprsenting URI in the OWL ontology file to the definition of the object class

Throws:

NotRegisteredException - when the object is not registered in the spatial database

getObjectLocation

public Location3D getObjectLocation(java.lang.String objectID)
                             throws NotRegisteredException

Description copied from interface: SpatialDatabase

This method allows to obtain location of a known spatial object.

Specified by:

getObjectLocation in interface SpatialDatabase

Parameters:

objectID - - id of the object return @see Location3D - object containg location coordinates as xyz

Throws:

NotRegisteredException - when the object is not registered in the spatial database

getObjectOrientation

public Orientation3D getObjectOrientation(java.lang.String objectID)
                                   throws NotRegisteredException

Description copied from interface: SpatialDatabase

This method allows to obtain orientation of a known spatial object.

Specified by:

getObjectOrientation in interface SpatialDatabase

Parameters:

objectID - - id of the object return @see Orientation3D - object containg orientation as xyz radiuses

Throws:

NotRegisteredException - when the object is not registered in the spatial database

getOccupiedSpace

public Block3D getOccupiedSpace(java.lang.String objectID)
                         throws NotRegisteredException

Description copied from interface: SpatialDatabase

This method allows to obtain aproximation of the occupied space of a known spatial object.

Specified by:

getOccupiedSpace in interface SpatialDatabase

Parameters:

objectID - - id of the object return @see Block3D - object containg inforationas about an occupied space as a 3d block

Throws:

NotRegisteredException - when the object is not registered in the spatial database

getBoundingPoints

public java.util.Vector<Location3D> getBoundingPoints(java.lang.String objectID)
                                               throws NotRegisteredException

Description copied from interface: SpatialDatabase

This method allows to obtain a vector of locations of the corners of the area bounding the object.

Specified by:

getBoundingPoints in interface SpatialDatabase

Parameters:

objectID - - id of the object return @see Block3D - object containg inforationas about an occupied space as a 3d block

Throws:

NotRegisteredException - when the object is not registered in the spatial database

findUsingAlternativeName

public java.util.Vector findUsingAlternativeName(java.lang.String objectAlternativeName)
                                          throws NotRegisteredException

Description copied from interface: SpatialDatabase

This method finds the spatial objects with the given alternative name

Specified by:

findUsingAlternativeName in interface SpatialDatabase

Parameters:

objectAlternativeName - - the alternative name of the object return Vector - id of the found object

Throws:

NotRegisteredException - when the object is not registered in the spatial database

getAlternativeNames

public java.util.Vector getAlternativeNames(java.lang.String objectID)
                                     throws NotRegisteredException

Description copied from interface: SpatialDatabase

This method get the alternative names of the spatial object.

Specified by:

getAlternativeNames in interface SpatialDatabase

Parameters:

objectID - - id of the updated object return Vector - the alternative names of the object

Throws:

NotRegisteredException - when the object is not registered in the spatial database

registerSpatialObject

public void registerSpatialObject(java.lang.String objectID,
                                  java.util.Set objectOntologyTypes,
                                  Location3D objectLocation,
                                  Orientation3D objectOrientation,
                                  Block3D objectOccupedSpace)
                           throws AlreadyRegisteredException

Description copied from interface: SpatialDatabase

This method allows to add information about a new spatial object. The description about the object contains information about its: ontological type (e.g. Robot, Craft, Area. etc.), location as 3 coordinates (xyz), orientation as 3 radiuses (from xyz axis) and the minimal space block occupied by the object

Specified by:

registerSpatialObject in interface SpatialDatabase

Parameters:

objectID - - id of the registered object

objectLocation - - initial location of the object represnted as @see Location3D

objectOrientation - - initial orientation of the object represnted as @see Orientation3D

objectOccupedSpace - - initial space occupied by the object represnted as @see Block3D

Throws:

AlreadyRegisteredException - when the object is already registered in the spatial database

registerSpatialObject

public void registerSpatialObject(java.lang.String objectID,
                                  java.util.Set objectOntologyType,
                                  Orientation3D objectOrientation,
                                  java.util.Vector<Location3D> boundingPoints)
                           throws AlreadyRegisteredException

Description copied from interface: SpatialDatabase

This method allows to add information about a new spatial object. The description about the object contains information about its: ontological type (e.g. Robot, Craft, Area. etc.), location as 3 coordinates (xyz), orientation as 3 radiuses (from xyz axis) and the minimal space block occupied by the object

Specified by:

registerSpatialObject in interface SpatialDatabase

Parameters:

objectID - - id of the registered object

objectOntologyType - - set of string representing URI in the OWL ontology file to the definition of the object class

objectOrientation - - initial orientation of the object represnted as @see Orientation3D

boundingPoints - - vector with locations of the corners of the area bounding the object

Throws:

AlreadyRegisteredException - when the object is already registered in the spatial database

deregisterSpatialObject

public void deregisterSpatialObject(java.lang.String objectID)
                             throws NotRegisteredException

Description copied from interface: SpatialDatabase

Deregister object identified by the given objectID and its spatial properties in the SpatialReasoner.

Specified by:

deregisterSpatialObject in interface SpatialDatabase

Parameters:

objectID - String uniquely identifying registering object in the SpatialReasoner.

Throws:

NotRegisteredException - if the registering object has not been registered in the SpatialReasoner.

updateSpatialObject

public void updateSpatialObject(java.lang.String objectID,
                                Location3D objectLocation,
                                Orientation3D objectOrientation,
                                Block3D objectOccupedSpace)
                         throws NotRegisteredException

Description copied from interface: SpatialDatabase

This method allows to modify information about a known spatial object. The value null of a particular parameter is interpreted as information that the corresponding spatial property of the object has not changed.

Specified by:

updateSpatialObject in interface SpatialDatabase

Parameters:

objectID - - id of the updated object

objectLocation - - new location of the object represnted as @see Location3D

objectOrientation - - new orientation of the object represnted as @see Orientation3D

objectOccupedSpace - - new space occupied by the object represnted as @see Block3D

Throws:

NotRegisteredException - when the object is not registered in the spatial database

updateSpatialObject

public void updateSpatialObject(java.lang.String objectID,
                                Orientation3D objectOrientation,
                                java.util.Vector<Location3D> boundingPoints)
                         throws NotRegisteredException

Description copied from interface: SpatialDatabase

This method allows to modify information about a known spatial object. The value null of a particular parameter is interpreted as information that the corresponding spatial property of the object has not changed.

Specified by:

updateSpatialObject in interface SpatialDatabase

Parameters:

objectID - - id of the updated object

objectOrientation - - new orientation of the object represnted as @see Orientation3D

boundingPoints - - vector with locations of the corners of the area bounding the object

Throws:

NotRegisteredException - when the object is not registered in the spatial database

setAlternativeName

public void setAlternativeName(java.lang.String objectID,
                               java.lang.String objectAlternativeName)
                        throws NotRegisteredException

Description copied from interface: SpatialDatabase

This method set the alternative name of the spatial object.

Specified by:

setAlternativeName in interface SpatialDatabase

Parameters:

objectID - - id of the updated object

objectAlternativeName - - the alternative name of the object

Throws:

NotRegisteredException - when the object is not registered in the spatial database

initVars

protected void initVars()