Geometry
Class Region

java.lang.Object
  |
  +--Geometry.Region

public class Region

extends java.lang.Object

Defines a named zone of a two-dimensional footprint (e.g., front, back) to be associated around an ObjectInference in the Reasoner and a Toy in the Sandbox. A topology is automatically generated to produce random numbers based on a bell distribution over the geometry of the region.

Version:

Created 17 November 2002

Author:

Dan Tappan

See Also:

Slice, RegionBounds, Topology

Field Summary

static float	DEFAULT_HORIZON
private boolean	m_is_committed
private boolean	m_is_front_oriented_otherwise_north
private int[][]	m_region
private RegionBounds	m_region_bounds
private float	m_region_horizon
private java.lang.String	m_region_name
private Topology	m_topology
static char	MODE_ADD
static char	MODE_INTERSECT
static char	MODE_SUBTRACT
static int	NUM_RINGS
static int	NUM_SECTORS
static float	REGION_SECTOR_AZIMUTH_STEP
static float	TOPOLOGY_SECTOR_AZIMUTH_STEP

Constructor Summary

Region(java.lang.String name)
Creates a new, empty Region, which is a collection of occupied cells in a projection composed of rings and sectors.

Region(java.lang.String name, java.lang.String slice_definitions)
Creates a new Region, which is a collection of the specified cells in a projection composed of rings and sectors.

Method Summary

void	addSlice(Slice slice) Adds a Slice to this region.
void	addSlice(Slice slice, char mode) Adds a Slice according to a logical mode.
void	addSlices(java.lang.String slice_definitions) Adds a set of Slices to this region according to logical modes.
void	clear() Clears all occupied cells in the region.
Region	commit(float distribution_decay_rate, float horizon, boolean is_front_oriented) Completes the transaction of adding slices to this region and results in the creation and population of the random topology based on the geometry.
protected void	commit(Region region1, Region region2, float horizon, boolean is_front_oriented) Performs the same action as commit(float, float), but on a new region created from the logical join of two existing regions with defined topologies.
boolean	containsPosition(ObjectInference object_inference, Position position) Returns whether a position is within this region.
private void	determineRegionBounds() Calculates the outermost volume a region occupies in terms of a start and end value for its rings and sectors.
RegionBounds	getBounds() Returns the outermost volume a region occupies in terms of a start and end value for its rings and sectors.
float	getHorizon() Returns how far this region extends across the world.
Position	getInverseRandomPosition(ObjectInference source_object_inference, ObjectInference target_object_inference) Returns a random position within the region.
Region	getLogicalEquivalence(Region region) Returns the equivalence (exclusive OR) of two regions and their topologies.
Region	getLogicalIntersection(Region region) Returns the intersection of two regions and their topologies.
Region	getLogicalUnion(Region region) Returns the union of two regions and their topologies.
java.lang.String	getName() Returns the name of this region.
static int	getNextSector(int sector) Returns the next geometry sector number.
static RegionCoordinate	getPolarFromCartesian(double x, double y) Returns a polar coordinate from a cartesian one.
static int	getPreviousSector(int sector) Returns the previous geometry sector number.
Position	getRandomPosition(ObjectInference object_inference) Returns a random position within the region.
Topology	getTopology() Returns the topology of the region.
RegionCoordinate	getTranslatedCoordinate(Position position, ObjectInference object_inference) Returns the ring and sector best corresponding to a position.
Position	getTranslatedPosition(RegionCoordinate topology_coordinate, ObjectInference object_inference, boolean use_topology_otherwise_geometry_coordinates, boolean is_offset) Returns the position corresponding to a ring and sector.
boolean	isCellOccupied(int ring, int sector) Returns whether a cell is occupied within the projection.
boolean	isFrontOriented() Gets the region orientation, which forces the first sector always to point toward either the front of the object this region is associated with or toward north.
boolean	isValidCoordinate(float ring, float sector) Returns whether a cell is part of a valid projection.
boolean	isValidCoordinate(RegionCoordinate coordinate) Returns whether a cell is part of a valid projection.
boolean	overlapsRegion(ObjectInference object_inference1, ObjectInference object_inference2, Region region2) Returns whether a region overlaps this region.
protected void	setCellOccupied(int ring, int sector) Sets whether a cell is occupied within the projection.
java.lang.String	toString() Returns a string representation of this object.
java.lang.String	toString(boolean list_cells) Returns a string representation of this object.
private void	verifyIsCommitted() Verifies that a commit has been performed on the region to prevent inappropriate access to certain methods.

Methods inherited from class java.lang.Object

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

Field Detail

NUM_RINGS

public static final int NUM_RINGS

See Also:

Constant Field Values

NUM_SECTORS

public static final int NUM_SECTORS

See Also:

Constant Field Values

MODE_ADD

public static final char MODE_ADD

See Also:

Constant Field Values

MODE_SUBTRACT

public static final char MODE_SUBTRACT

See Also:

Constant Field Values

MODE_INTERSECT

public static final char MODE_INTERSECT

See Also:

Constant Field Values

REGION_SECTOR_AZIMUTH_STEP

public static final float REGION_SECTOR_AZIMUTH_STEP

See Also:

Constant Field Values

TOPOLOGY_SECTOR_AZIMUTH_STEP

public static final float TOPOLOGY_SECTOR_AZIMUTH_STEP

See Also:

Constant Field Values

DEFAULT_HORIZON

public static final float DEFAULT_HORIZON

See Also:

Constant Field Values

m_region_horizon

private float m_region_horizon

m_region_name

private java.lang.String m_region_name

m_topology

private Topology m_topology

m_region

private int[][] m_region

m_is_committed

private boolean m_is_committed

m_region_bounds

private RegionBounds m_region_bounds

m_is_front_oriented_otherwise_north

private boolean m_is_front_oriented_otherwise_north

Constructor Detail

Region

public Region(java.lang.String name)

Creates a new, empty Region, which is a collection of occupied cells in a projection composed of rings and sectors. Use addSlice to build the region.

Note: due to assumptions in the way the random topology is inferred, only continuous wedge-shaped and toroidal regions are supported fully. Other shapes will produce valid regions, but the topology will be incorrect. See Topology.createDistribution() for details.

Parameters:

name - - the region name

See Also:

addSlice(Geometry.Slice), addSlices(java.lang.String)

Region

public Region(java.lang.String name,
              java.lang.String slice_definitions)
       throws java.lang.Exception

Creates a new Region, which is a collection of the specified cells in a projection composed of rings and sectors. Each ring defaults to having the same relative thickness.

Parameters:

name - - the region name

slice_definitions - - the mode-delimited slice definitions

Throws:

java.lang.Exception - - if any slice cannot be added

See Also:

Slice, addSlices(java.lang.String)

Method Detail

addSlice

public void addSlice(Slice slice)
              throws java.lang.Exception

Adds a Slice to this region.

Parameters:

slice - - the slice

Throws:

java.lang.Exception - - if the slice cannot be added

addSlices

public void addSlices(java.lang.String slice_definitions)
               throws java.lang.Exception

Adds a set of Slices to this region according to logical modes. See Slice for the definition of a slice. The slice definitions here are delimited according to mode as follows:

   + = Add slice (union)
   - = Subtract slice (difference)
   ^ = Intersect slice
 

A space delimiter is also treated as an add.

The expression is parsed in left-associative manner.

Parameters:

slice_definitions - - the set of slices; e.g., a14a03hh^b15c02hh+d16e01hh

Throws:

java.lang.Exception - - if any of the slice definitions is invalid

See Also:

Slice

addSlice

public void addSlice(Slice slice,
                     char mode)
              throws java.lang.Exception

Adds a Slice according to a logical mode.

Parameters:

slice - - the slice

mode - - the mode

Throws:

java.lang.Exception - - if the mode is invalid

See Also:

MODE_ADD, MODE_SUBTRACT, MODE_INTERSECT

clear

public void clear()

Clears all occupied cells in the region.

commit

public Region commit(float distribution_decay_rate,
                     float horizon,
                     boolean is_front_oriented)

Completes the transaction of adding slices to this region and results in the creation and population of the random topology based on the geometry.

Many Region methods are unavailable until this is called. No slices can be added afterwards.

Parameters:

distribution_decay_rate - - the slope adjustment for automatically calculating probability distributions

horizon - - how far this region extends across the world

is_front_oriented - - whether the first sector always to point toward the front of the object this region is associated with or toward north

Returns:

this object, as a convenience to allow a region to be created and committed in a single statement; e.g., region_set.addRegion((new Region("far", "f01f32")).commit(2.0, 10.0, true));

See Also:

Topology.Topology(Geometry.Region, Geometry.Topology, Geometry.Topology), isFrontOriented()

commit

protected void commit(Region region1,
                      Region region2,
                      float horizon,
                      boolean is_front_oriented)

Performs the same action as commit(float, float), but on a new region created from the logical join of two existing regions with defined topologies.

Parameters:

region1 - - the first region contributing to the join

region2 - - the second region contributing to the join

horizon - - how far this region extends across the world

is_front_oriented - - whether the first sector always to point toward the front of the object this region is associated with or toward north

See Also:

getLogicalIntersection(Geometry.Region), getLogicalUnion(Geometry.Region), getLogicalEquivalence(Geometry.Region), isFrontOriented()

containsPosition

public boolean containsPosition(ObjectInference object_inference,
                                Position position)

Returns whether a position is within this region. This accounts for any scaling, translation, and rotation of the object inference associated with it.

This method is not available until commit() is called.

Parameters:

object_inference - - the object the region is associated with

position - - the position

Returns:

the outcome

determineRegionBounds

private void determineRegionBounds()

Calculates the outermost volume a region occupies in terms of a start and end value for its rings and sectors.

This method is not available until commit() is called.

getBounds

public RegionBounds getBounds()

Returns the outermost volume a region occupies in terms of a start and end value for its rings and sectors.

This method is not available until commit() is called.

Returns:

the region bounds

getHorizon

public float getHorizon()

Returns how far this region extends across the world.

Returns:

the distance

getInverseRandomPosition

public Position getInverseRandomPosition(ObjectInference source_object_inference,
                                         ObjectInference target_object_inference)

Returns a random position within the region. This accounts for any scaling, translation, and rotation of the object inference associated with it. Use this when the position of the target object inference is known and the position is needed for the source object inference.

This method is not available until commit() is called.

Parameters:

source_object_inference - - the source object inference with unknown position

target_object_inference - - the target object inference with known position

Returns:

the position component

See Also:

getRandomPosition(Reasoner.ObjectInference)

getLogicalEquivalence

public Region getLogicalEquivalence(Region region)

Returns the equivalence (exclusive OR) of two regions and their topologies.

This method is not available until commit() is called.

Parameters:

region - - the region

Returns:

the exclusive-or

See Also:

getLogicalIntersection(Geometry.Region), getLogicalUnion(Geometry.Region)

getLogicalIntersection

public Region getLogicalIntersection(Region region)

Returns the intersection of two regions and their topologies.

This method is not available until commit() is called.

Parameters:

region - - the region

Returns:

the intersection

See Also:

getLogicalEquivalence(Geometry.Region), getLogicalUnion(Geometry.Region)

getLogicalUnion

public Region getLogicalUnion(Region region)

Returns the union of two regions and their topologies.

This method is not available until commit() is called.

Parameters:

region - - the region

Returns:

the union

See Also:

getLogicalIntersection(Geometry.Region), getLogicalUnion(Geometry.Region)

getName

public java.lang.String getName()

Returns the name of this region.

Returns:

the name

getNextSector

public static int getNextSector(int sector)

Returns the next geometry sector number. This adds 1 to the current sector except when the last sector needs to wrap around to the first.

Parameters:

sector - - the sector

Returns:

the next sector number

getPolarFromCartesian

public static RegionCoordinate getPolarFromCartesian(double x,
                                                     double y)

Returns a polar coordinate from a cartesian one.

Parameters:

x - - the x coordinate

y - - the y coordinate

Returns:

the coordinate, which is coaxed into the ring and sector fields of a RegionCoordinate for convenience. Azimuth is returned in radians

getPreviousSector

public static int getPreviousSector(int sector)

Returns the previous geometry sector number. This substract 1 to the current sector except when the first sector needs to wrap around to the last.

Parameters:

sector - - the sector

Returns:

the previous sector number

getRandomPosition

public Position getRandomPosition(ObjectInference object_inference)

Returns a random position within the region. This accounts for any scaling, translation, and rotation of the object inference associated with it. Use this when the position of the source object inference is known and the position is needed for a target object inference.

This method is not available until commit() is called.

Parameters:

object_inference - - the object the region is associated with

Returns:

the position component

See Also:

getInverseRandomPosition(Reasoner.ObjectInference, Reasoner.ObjectInference)

getTopology

public Topology getTopology()

Returns the topology of the region.

This method is not available until commit() is called.

Returns:

the topology

getTranslatedCoordinate

public RegionCoordinate getTranslatedCoordinate(Position position,
                                                ObjectInference object_inference)

Returns the ring and sector best corresponding to a position. This accounts for any scaling, translation, and rotation of the object inference.

Parameters:

position - - the position

object_inference - - the object the region is associated with

Returns:

the coordinate

See Also:

getTranslatedPosition(Geometry.RegionCoordinate, Reasoner.ObjectInference, boolean, boolean)

getTranslatedPosition

public Position getTranslatedPosition(RegionCoordinate topology_coordinate,
                                      ObjectInference object_inference,
                                      boolean use_topology_otherwise_geometry_coordinates,
                                      boolean is_offset)

Returns the position corresponding to a ring and sector. This accounts for any scaling, translation, and rotation of the object inference.

Parameters:

topology_coordinate - - the ring and sector from the topology

object_inference - - the object the region is associated with

use_topology_otherwise_geometry_coordinates - - which coordinate system to use

is_offset - - whether to offset the returned position by half a topology cell for better alignment in a topology mesh

Returns:

the position

See Also:

getTranslatedCoordinate(Renderer.Position, Reasoner.ObjectInference)

isCellOccupied

public boolean isCellOccupied(int ring,
                              int sector)

Returns whether a cell is occupied within the projection. Occupied cells comprise a region.

This method is not available until commit() is called.

Parameters:

ring - - the ring of the cell to check

sector - - the sector of the cell to check

Returns:

the outcome

isFrontOriented

public boolean isFrontOriented()

Gets the region orientation, which forces the first sector always to point toward either the front of the object this region is associated with or toward north.

Returns:

whether the orientation is front otherwise north

isValidCoordinate

public boolean isValidCoordinate(float ring,
                                 float sector)

Returns whether a cell is part of a valid projection.

Parameters:

ring - - the ring to check

sector - - the sector to check

Returns:

the outcome

isValidCoordinate

public boolean isValidCoordinate(RegionCoordinate coordinate)

Returns whether a cell is part of a valid projection.

Parameters:

coordinate - - the coordinate to check

Returns:

the outcome

overlapsRegion

public boolean overlapsRegion(ObjectInference object_inference1,
                              ObjectInference object_inference2,
                              Region region2)

Returns whether a region overlaps this region. This accounts for any scaling, translation, and rotation of the object inferences associated with them.

This method is not available until commit() is called.

Parameters:

object_inference1 - - the object inference this region is associated with

object_inference2 - - the object inference region2 is associated with

region2 - - the region to check against this one

Returns:

the outcome

setCellOccupied

protected void setCellOccupied(int ring,
                               int sector)

Sets whether a cell is occupied within the projection. Occupied cells comprise a region.

Parameters:

ring - - the ring of the cell to occupy

sector - - the sector of the cell to occupy

toString

public java.lang.String toString()

Returns a string representation of this object. Individual cells are not listed; to do so, use the other variant of this method.

Overrides:

toString in class java.lang.Object

Returns:

the String representation

See Also:

Support.toPrettyString(java.lang.String), toString(boolean)

toString

public java.lang.String toString(boolean list_cells)

Returns a string representation of this object.

Parameters:

list_cells - - whether each cell should be listed

Returns:

the String representation

See Also:

Support.toPrettyString(java.lang.String)

verifyIsCommitted

private void verifyIsCommitted()

Verifies that a commit has been performed on the region to prevent inappropriate access to certain methods. An assertion failure occurs if not.

See Also:

commit(float, float, boolean)