ptolemy.domains.wireless.lib
Class TerrainProperty

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.domains.wireless.lib.TerrainProperty

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, PropertyTransformer, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class TerrainProperty
extends TypedAtomicActor
implements PropertyTransformer

This actor models an obstacle that attenuates signals that traverse it. The obstacle has a geometry given by the xyPoints parameter. By default, the attenuation is infinite, meaning that the obstacle completely blocks a signal. By increasing the attenuationDepth parameter you can specify partial attenuation that depends on the geometry of the obstacle. If attenuationDepth has value x and the signal traverses distance y through the obstacle, then the power of the signal is reduced by a factor of

   exp(log(0.5) * y / x)
 

Thus, if x = y, then the power is reduced to half (3dB). The algorithm used here only works for convex obstacle shapes.

This actor implements the PropertyTransformer interface. It register itself with the wireless channel specified by the channelName parameter. The channel may call it getProperty() method to get the property.

Since:

Ptolemy II 4.0

Version:

$Id: TerrainProperty.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Yang Zhao and William Douglas (contributor: Edward A. Lee)

See Also:

Serialized Form

Accepted Rating:

Red (pjb2e)

Proposed Rating:

Yellow (eal)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

private double	_attenuation
private WirelessChannel	_channel
private java.lang.String	_channelName
private EditorIcon	_icon
private int	_number
private int	_numberOfPoints
private double[]	_offset
private FilledShapeAttribute	_terrain
private int[]	_xPoints
private int[]	_yPoints
Parameter	attenuationDepth The width of material that will attenuate a signal power by 50% (3dB).
StringParameter	channelName The name of the channel.
private static java.lang.String	LOCATION_ATTRIBUTE_NAME
Parameter	xyPoints The x/y coordinates of the obstable.

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

TerrainProperty(CompositeEntity container, java.lang.String name)
Construct an actor with the specified container and name.

Method Summary

private double[]	_lineSegmentIntersectionPoint(double[] a1, double[] a2, double[] b1, double[] b2) Return the point where two lines segments intersect.
private double[]	_locationOf(WirelessIOPort port) Return the location of the given WirelessIOPort.
private double[]	_polygonCenter() Return the center coordinates of the polygon icon.
private double	_polygonDepthBetweenPorts(double[] p1, double[] p2) Return the depth of the terrain that resides directly between the two points.
void	attributeChanged(Attribute attribute) Override the base class to parse the model specified if the attribute is modelFileOrURL.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
void	initialize() Register PropertyTransformers with the Channel.
RecordToken	transformProperties(RecordToken properties, WirelessIOPort sender, WirelessIOPort destination) Check whether the path between the sender and receiver is intersected with the terrain shape.
void	wrapup() Override the base class to call wrap up to unregister this with the channel.

Methods inherited from class ptolemy.actor.TypedAtomicActor

_addPort, _fireAt, _fireAt, attributeTypeChanged, clone, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, fire, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, postfire, prefire, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

fire, isFireFunctional, isStrict, iterate, postfire, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, preinitialize, removeInitializable

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

channelName

public StringParameter channelName

The name of the channel. The default name is "TerrainChannel".

attenuationDepth

public Parameter attenuationDepth

The width of material that will attenuate a signal power by 50% (3dB). This has the same units as the xyPoints parameter, which specifies the geometry of the obstable. The default value is 0.0, which means infinite attenuation (no signal gets through).

xyPoints

public Parameter xyPoints

The x/y coordinates of the obstable. This is an array of integers specifying a geometry. The icon will have the same geometry. The default value is an array of integer pairs: {{0, 0}, {0, 5}, {20, 5}, {20, 0}}

_channel

private WirelessChannel _channel

_xPoints

private int[] _xPoints

_yPoints

private int[] _yPoints

_icon

private EditorIcon _icon

_terrain

private FilledShapeAttribute _terrain

_numberOfPoints

private int _numberOfPoints

_attenuation

private double _attenuation

_number

private int _number

_offset

private double[] _offset

_channelName

private java.lang.String _channelName

LOCATION_ATTRIBUTE_NAME

private static final java.lang.String LOCATION_ATTRIBUTE_NAME

See Also:

Constant Field Values

Constructor Detail

TerrainProperty

public TerrainProperty(CompositeEntity container,
                       java.lang.String name)
                throws NameDuplicationException,
                       IllegalActionException

Construct an actor with the specified container and name.

Parameters:

container - The container.

name - The name.

Throws:

IllegalActionException - If the entity cannot be contained by the proposed container.

NameDuplicationException - If the container already has an actor with this name.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Override the base class to parse the model specified if the attribute is modelFileOrURL.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the object into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there). The result is an object with no container.

Overrides:

clone in class AtomicActor

Parameters:

workspace - The workspace for the cloned object.

Returns:

The new Attribute.

Throws:

java.lang.CloneNotSupportedException - Not thrown in this base class

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

initialize

public void initialize()
                throws IllegalActionException

Register PropertyTransformers with the Channel.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If a derived class throws it.

transformProperties

public RecordToken transformProperties(RecordToken properties,
                                       WirelessIOPort sender,
                                       WirelessIOPort destination)
                                throws IllegalActionException

Check whether the path between the sender and receiver is intersected with the terrain shape. If yes, set the "power" field in the property to be zero, otherwise, do nothing.

Specified by:

transformProperties in interface PropertyTransformer

Parameters:

properties - The transform properties.

sender - The sending port.

destination - The receiving port.

Returns:

The modified transform properties.

Throws:

IllegalActionException - If failed to execute the model.

wrapup

public void wrapup()
            throws IllegalActionException

Override the base class to call wrap up to unregister this with the channel.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class AtomicActor

Throws:

IllegalActionException - Not thrown in this base class.

_locationOf

private double[] _locationOf(WirelessIOPort port)
                      throws IllegalActionException

Return the location of the given WirelessIOPort.

Parameters:

port - A port with a location.

Returns:

The location of the port.

Throws:

IllegalActionException - If a valid location attribute cannot be found.

_polygonCenter

private double[] _polygonCenter()

Return the center coordinates of the polygon icon.

Returns:

The location of the polygon center.

_polygonDepthBetweenPorts

private double _polygonDepthBetweenPorts(double[] p1,
                                         double[] p2)

Return the depth of the terrain that resides directly between the two points. The order of the points is not important.

Parameters:

p1 - The first reference point.

p2 - The second reference point.

Returns:

The depth of the terrain object between the supplied points.

_lineSegmentIntersectionPoint

private double[] _lineSegmentIntersectionPoint(double[] a1,
                                               double[] a2,
                                               double[] b1,
                                               double[] b2)
                                        throws IllegalActionException

Return the point where two lines segments intersect. The two line segments are identified by their start and end points. Should the lines not intersect, an IllegalActionException is thrown.

Parameters:

a1 - Endpoint on the first line segment.

a2 - Endpoint on the first line segment.

b1 - Endpoint on the second line segment.

b2 - Endpoint on the second line segment.

Returns:

Location of the intersection point.

Throws:

IllegalActionException - If the line segments do not intersect or if the math results in a determinate of 0.