messif.objects
Class BallRegion

java.lang.Object
  extended by messif.objects.UniqueID
      extended by messif.objects.AbstractObject
          extended by messif.objects.LocalAbstractObject
              extended by messif.objects.BallRegion
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<UniqueID>, Clearable
Direct Known Subclasses:
BucketBallRegion

public class BallRegion
extends LocalAbstractObject

This class represents a ball region, i.e. a partition of the metric space that holds objects that are within a specified radius from the central object (pivot). The distance function is compatible if and only if the pivot distance function is compatible.

See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class messif.objects.LocalAbstractObject
LocalAbstractObject.DataEqualObject
 
Field Summary
protected  LocalAbstractObject pivot
          Center of the ball region
protected  float radius
          Radius of this region
 
Fields inherited from class messif.objects.LocalAbstractObject
counterDistanceComputations, counterLowerBoundDistanceComputations, counterUpperBoundDistanceComputations, MAX_DISTANCE, MIN_DISTANCE, suppData, UNKNOWN_DISTANCE
 
Constructor Summary
BallRegion()
          Creates a new instance of BallRegion with initially empty ball region
BallRegion(java.io.BufferedReader stream)
          Creates a new instance of BallRegion from stream.
BallRegion(LocalAbstractObject pivot, float radius)
          Creates a new instance of BallRegion with specified pivot and radius
 
Method Summary
 LocalAbstractObject cloneRandomlyModify(java.lang.Object... args)
          Random copy of ball region is not implemented, thus this method always throws an exception.
 boolean dataEquals(java.lang.Object obj)
          Indicates whether some other object has the same data as this one.
 int dataHashCode()
          Returns a hash code value for this ball region's data, i.e. the hash code of the pivot.
protected  float getDistanceImpl(LocalAbstractObject obj, float distThreshold)
          Metric distance function that measures the distance of an arbitrary object to this region.
 float getDistanceRegion(BallRegion region, float distThreshold)
          Metric distance function between two ball regions.
 float getDistanceRegion(LocalAbstractObject regionPivot, float regionRadius, float distThreshold)
          Metric distance function between two ball regions.
protected  float getDistanceRegionImpl(BallRegion region, float distThreshold)
          Metric distance function between two ball regions.
protected  float getDistanceRegionImpl(float regionsPivotDistance, float regionRadius)
          Actual computation of the distance if the distance between regions' pivots is known.
 float getOverlapWith(LocalAbstractObject regionPivot, float regionRadius)
          Returns the covering overlap (as distance) between this region and the region specified by regionPivot and regionRadius.
 LocalAbstractObject getPivot()
          Returns current pivot of this ball region.
 float getRadius()
          Returns current radius of this ball region.
 int getSize()
          Returns the size of this ball region in bytes.
 boolean isCoveredByRegion(LocalAbstractObject regionPivot, float regionRadius, float distThreshold)
          Returns true if this ball region is covered by at least distThreshold area of the ball region specified by regionPivot and regionRadius.
 boolean isCoveringRegion(LocalAbstractObject regionPivot, float regionRadius, float distThreshold)
          Returns true if this ball region covers at least distThreshold area of the ball region specified by regionPivot and regionRadius.
 void setPivot(LocalAbstractObject pivot, boolean updateRadius)
          Sets the pivot for this ball region.
 void setRadius(float radius)
          Sets the radius for this ball region.
protected  void writeData(java.io.OutputStream stream)
          Store this object's data to a text stream.
 
Methods inherited from class messif.objects.LocalAbstractObject
binarySerialize, clearSurplusData, clone, clone, create, create, createMetaDistancesHolder, excludeUsingPrecompDist, getBinarySize, getDistance, getDistance, getDistance, getDistanceFilter, getDistanceFilter, getDistanceFilter, getDistanceLowerBound, getDistanceLowerBoundImpl, getDistanceUpperBound, getDistanceUpperBoundImpl, getMaxDistance, getNormDistance, getRandomChar, getRandomNormal, chainDestroy, chainFilter, includeUsingPrecompDist, readObjectComments, unchainFilter, write, write
 
Methods inherited from class messif.objects.AbstractObject
clone, getLocatorURI, getNoDataObject, getObjectID, getObjectKey, setObjectKey, toString
 
Methods inherited from class messif.objects.UniqueID
compareTo, equals, hashCode
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

pivot

protected LocalAbstractObject pivot
Center of the ball region


radius

protected float radius
Radius of this region

Constructor Detail

BallRegion

public BallRegion()
Creates a new instance of BallRegion with initially empty ball region


BallRegion

public BallRegion(LocalAbstractObject pivot,
                  float radius)
Creates a new instance of BallRegion with specified pivot and radius

Parameters:
pivot - the pivot for the new ball region
radius - the radius for the new ball region

BallRegion

public BallRegion(java.io.BufferedReader stream)
           throws java.io.IOException,
                  java.lang.NumberFormatException,
                  java.lang.IllegalArgumentException,
                  java.lang.ClassNotFoundException
Creates a new instance of BallRegion from stream.

Parameters:
stream - the stream to load ball region from
Throws:
java.io.IOException - if an error occurs during reading from the stream
java.lang.NumberFormatException - if the stream's object is not valid ball region
java.lang.IllegalArgumentException - if the stream's object is not valid ball region
java.lang.ClassNotFoundException - if the stream's object is not valid ball region
Method Detail

writeData

protected void writeData(java.io.OutputStream stream)
                  throws java.io.IOException
Store this object's data to a text stream. This method have the opposite deserialization in constructor.

Specified by:
writeData in class LocalAbstractObject
Parameters:
stream - the stream to store this object to
Throws:
java.io.IOException - if there was an error while writing to stream

getRadius

public float getRadius()
Returns current radius of this ball region.

Returns:
current radius of this ball region

getPivot

public LocalAbstractObject getPivot()
Returns current pivot of this ball region.

Returns:
current pivot of this ball region

setRadius

public void setRadius(float radius)
               throws java.lang.IllegalArgumentException
Sets the radius for this ball region.

Parameters:
radius - the new radius
Throws:
java.lang.IllegalArgumentException - if the specified radius is negative

setPivot

public void setPivot(LocalAbstractObject pivot,
                     boolean updateRadius)
Sets the pivot for this ball region. Note, that the radius is set to LocalAbstractObject.MAX_DISTANCE if updateRadius is true.

Parameters:
pivot - the new pivot
updateRadius - specifies whether to update the region's radius or not

getDistanceImpl

protected float getDistanceImpl(LocalAbstractObject obj,
                                float distThreshold)
Metric distance function that measures the distance of an arbitrary object to this region. If the object is within this region, the distance is zero. Otherwise, the distance is measured from this region's boundary.

Specified by:
getDistanceImpl in class LocalAbstractObject
Parameters:
obj - the object to compute distance to
distThreshold - the threshold value on the distance
Returns:
the actual distance between obj and this region if the distance is lower than distThreshold. Otherwise the returned value is not guaranteed to be exact, but in this respect the returned value must be greater than the threshold distance.

getDistanceRegion

public float getDistanceRegion(BallRegion region,
                               float distThreshold)
Metric distance function between two ball regions.

Parameters:
region - the ball region to compute distance to
distThreshold - the threshold value on the distance
Returns:
returns the actual distance between the specified region and this one if the distance is lower than distThreshold. Otherwise the returned value is not guaranteed to be exact, but in this respect the returned value must be greater than the threshold distance.

getDistanceRegion

public float getDistanceRegion(LocalAbstractObject regionPivot,
                               float regionRadius,
                               float distThreshold)
Metric distance function between two ball regions.

Parameters:
regionPivot - the pivot (center) of the ball region to compute distance to
regionRadius - the radius of the ball region to compute distance to
distThreshold - the threshold value on the distance
Returns:
returns the actual distance between the specified region and this one if the distance is lower than distThreshold. Otherwise the returned value is not guaranteed to be exact, but in this respect the returned value must be greater than the threshold distance.

getDistanceRegionImpl

protected float getDistanceRegionImpl(BallRegion region,
                                      float distThreshold)
Metric distance function between two ball regions. Wrapper method to avoid incrementing statistics, because the statistics have already been incremented.

Parameters:
region - the ball region to compute distance to
distThreshold - the threshold value on the distance
Returns:
returns the actual distance between the specified region and this one if the distance is lower than distThreshold. Otherwise the returned value is not guaranteed to be exact, but in this respect the returned value must be greater than the threshold distance.

getDistanceRegionImpl

protected float getDistanceRegionImpl(float regionsPivotDistance,
                                      float regionRadius)
Actual computation of the distance if the distance between regions' pivots is known.

Parameters:
regionsPivotDistance - the distance of the regions' pivots
regionRadius - the radius of the ball region to compute distance to
Returns:
returns the actual distance between the two regions

getOverlapWith

public float getOverlapWith(LocalAbstractObject regionPivot,
                            float regionRadius)
Returns the covering overlap (as distance) between this region and the region specified by regionPivot and regionRadius. If the two regions touch but have no common area, zero is returned. If the two regions do not even touch, this method returns negative value.

Parameters:
regionPivot - the pivot (center) of the ball region to get the coverage for
regionRadius - the radius of the ball region to get the coverage for
Returns:
returns the covering overlap (as distance) between this region and the specified one

isCoveringRegion

public boolean isCoveringRegion(LocalAbstractObject regionPivot,
                                float regionRadius,
                                float distThreshold)
Returns true if this ball region covers at least distThreshold area of the ball region specified by regionPivot and regionRadius. The distThreshold is the maximal distance that a region's object can be outside this region. If the threshold is zero, the evaluated region must be fully within this one. If the two regions do not even touch, this method returns false whatever the value of the threshold is.

Parameters:
regionPivot - the pivot (center) of the ball region to get the coverage for
regionRadius - the radius of the ball region to get the coverage for
distThreshold - the threshold distance value on the non-overlaping area
Returns:
returns true if the specified ball region is within this one

isCoveredByRegion

public boolean isCoveredByRegion(LocalAbstractObject regionPivot,
                                 float regionRadius,
                                 float distThreshold)
Returns true if this ball region is covered by at least distThreshold area of the ball region specified by regionPivot and regionRadius. The distThreshold is the maximal distance that an object from this region can be outside the specified region. If the threshold is zero, the this region must be fully within the specified region. If the two regions do not even touch, this method returns false whatever the value of the threshold is.

Parameters:
regionPivot - the pivot (center) of the ball region to get the coverage for
regionRadius - the radius of the ball region to get the coverage for
distThreshold - the threshold distance value on the non-overlaping area
Returns:
returns true if the this ball region is within the specified one

getSize

public int getSize()
Returns the size of this ball region in bytes. Specifically, it is the size of the pivot plus the float number for radius.

Specified by:
getSize in class LocalAbstractObject
Returns:
the size of this ball region in bytes

dataEquals

public boolean dataEquals(java.lang.Object obj)
Indicates whether some other object has the same data as this one.

Specified by:
dataEquals in class LocalAbstractObject
Parameters:
obj - the reference object with which to compare.
Returns:
true if this object is the same as the obj argument; false otherwise.

dataHashCode

public int dataHashCode()
Returns a hash code value for this ball region's data, i.e. the hash code of the pivot.

Specified by:
dataHashCode in class LocalAbstractObject
Returns:
a hash code value for this ball region's data

cloneRandomlyModify

public LocalAbstractObject cloneRandomlyModify(java.lang.Object... args)
                                        throws java.lang.UnsupportedOperationException
Random copy of ball region is not implemented, thus this method always throws an exception.

Overrides:
cloneRandomlyModify in class LocalAbstractObject
Parameters:
args - the value is ignored
Returns:
nothing because an exception is thrown
Throws:
java.lang.UnsupportedOperationException - always