org.abora.white.spaces.basic
Class Mapping

java.lang.Object
  |
  +--org.abora.white.xpp.basic.Heaper
        |
        +--org.abora.white.spaces.basic.Mapping

Direct Known Subclasses:

CompositeMapping, ConstantMapping, Dsp, EmptyMapping, SimpleMapping

public abstract class Mapping

extends Heaper

A mapping is a general mapping from one coordinate space to another, with few of the guarantees provided by Dsps. In particular, the source and destination coordinate spaces can be different, and the mapping doesn''t have to be everywhere defined (but it has to say where it is defined via "domain" and "range" messages). A mapping doesn''t have to be unique--the same domain position may map to multiple range positions and vice versa. A mapping of a XuRegion must yield another XuRegion, but a mapping of a simple region doesn''t have to yield a simple region. A useful and valid way to think of a Mapping is as a (possibly infinite) set of pairs (a mathematical set, not a ScruSet). The domain region consists of the first elements of each pair, and the range region consists of the second elements. A mapping is most useful as a representation of a version comparison of two different organizations of common elements. The mapping would tell how positions in one organization correspond to positions in the other.

Constructor Summary

protected	Mapping()
protected	Mapping(Rcvr rcvr)

Method Summary

int	actualHashForEqual() Defined by subclasses to produce the value returned by hashForEqual.
abstract Mapping	appliedAfter(Dsp dsp) Defined by the equivalence: M->transformedBy(D)->of(R) isEqual (M->of(D->of(R))) for all regions R in the domainSpace of M.
Mapping	combine(Mapping other) Essential.
abstract CoordinateSpace	coordinateSpace() the coordinate space of the domain of the Mapping
abstract XnRegion	domain() Essential.
CoordinateSpace	domainSpace() The coordinate space of the domain of the Mapping
abstract Mapping	fetchCombine(Mapping mapping) if I know how to combine the two into a single mapping, then I do so
abstract Dsp	fetchDsp() if this is a Dsp or a Dsp retricted to some domain, return the underlying Dsp.
static void	info() {Mapping CLIENT} combine: other {Mapping} {XuRegion CLIENT} domain {CoordinateSpace CLIENT} domainSpace {Mapping CLIENT} inverse {BooleanVar CLIENT} isComplete {BooleanVar CLIENT} isIdentity {Position CLIENT} of: before {Position} {XuRegion CLIENT} ofAll: before {XuRegion} {XuRegion CLIENT} range {CoordinateSpace CLIENT} rangeSpace {Mapping CLIENT} restrict: region {XuRegion} {Stepper CLIENT of: Mapping} simplerMappings {Mapping CLIENT} unrestricted
abstract Mapping	inverse() Essential.
abstract Position	inverseOf(Position after) Inverse transform a position.
abstract XnRegion	inverseOfAll(XnRegion after) Inverse transform of a region.
IntegerValue	inverseOfInt(IntegerValue pos) Unboxed version of 'this->inverseOf (xuInteger(pos))'.
abstract boolean	isComplete() Essential.
abstract boolean	isIdentity() Essential.
static Mapping	make(CoordinateSpace cs, CoordinateSpace rs) Make an empty mapping from cs to rs.
static Mapping	make(CoordinateSpace cs, CoordinateSpace rs, ImmuSet mappings) The combine of all the mappings in 'mappings' All domains must be in cs and all ranges in rs.
static Mapping	make(CoordinateSpace cs, XnRegion values) Make a constant mapping from all positions in cs to all positions in values.
abstract Position	of(Position before) Transform a position.
abstract XnRegion	ofAll(XnRegion before) Essential.
IntegerValue	ofInt(IntegerValue pos) Unboxed version of 'this->of (xuInteger(pos))'.
abstract Mapping	preCompose(Dsp dsp) There is no sensible explanation for what this message does on Mappings which aren't Dsps.
abstract XnRegion	range() Essential.
abstract CoordinateSpace	rangeSpace() The coordinate space of the range of the transformation
abstract Mapping	restrict(XnRegion region) Essential.
abstract Mapping	restrictRange(XnRegion region) Restrict the range.
abstract ImmuSet	simpleMappings() return a set of simple mappings that would combine to this one
abstract ImmuSet	simpleRegionMappings() return a set of mappings with simple regions as their domains that would combine to this one.
Stepper	simplerMappings() Essential.
abstract Mapping	transformedBy(Dsp dsp) Defined by the equivalence: M->transformedBy(D)->of(R) isEqual (D->of(M->of(R))) for all regions R in the domainSpace of M.
Mapping	unrestricted() Essential.

Methods inherited from class org.abora.white.xpp.basic.Heaper

destroy, destruct, equals, hashForEqual, isEqual, printContentsOn, printOn, sendSelfTo, toString

Methods inherited from class java.lang.Object

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

Constructor Detail

Mapping

protected Mapping()

Mapping

protected Mapping(Rcvr rcvr)

Method Detail

coordinateSpace

public abstract CoordinateSpace coordinateSpace()

the coordinate space of the domain of the Mapping

domain

public abstract XnRegion domain()

Essential. region in which it is valid.

domainSpace

public CoordinateSpace domainSpace()

The coordinate space of the domain of the Mapping

fetchDsp

public abstract Dsp fetchDsp()

if this is a Dsp or a Dsp retricted to some domain, return the underlying Dsp. Otherwise NULL.

isComplete

public abstract boolean isComplete()

Essential. Return true if each Position in the domain is mapped to every Position in the range.

isIdentity

public abstract boolean isIdentity()

Essential. True if this is the identify mapping on the entire space.

range

public abstract XnRegion range()

Essential. region in which inverse is valid. Same as the region that the domain region maps to. For you mathematicians, it is the image of the domain under the mapping.

rangeSpace

public abstract CoordinateSpace rangeSpace()

The coordinate space of the range of the transformation

simpleMappings

public abstract ImmuSet simpleMappings()

return a set of simple mappings that would combine to this one

simpleRegionMappings

public abstract ImmuSet simpleRegionMappings()

return a set of mappings with simple regions as their domains that would combine to this one.

simplerMappings

public Stepper simplerMappings()

Essential. Break this Mapping up into simpler Mappings which can be combined together to get this one.

unrestricted

public Mapping unrestricted()

Essential. If this is a 'simpler' Mapping, and not isFull, then return a yet simpleMapping of some class from which you can get more information. Note that m->restrict (region)->unrestricted () is not necessarily the same as m, since information may be lost.

inverseOf

public abstract Position inverseOf(Position after)

Inverse transform a position. Must BLAST if there isn't a unique inverse. 'a->isEqual (this->of (b))' iff 'b->isEqual (this->inverseOf (a))'.

inverseOfAll

public abstract XnRegion inverseOfAll(XnRegion after)

Inverse transform of a region. 'a->isEqual (this->of (b))' iff 'b->isEqual (this->inverseOf (a))'.

inverseOfInt

public IntegerValue inverseOfInt(IntegerValue pos)

Unboxed version of 'this->inverseOf (xuInteger(pos))'. See discussion in the XuInteger class comment about boxed and unboxed protocols

of

public abstract Position of(Position before)

Transform a position. 'before' must be a Position of my domain space. Iff 'before' is in the domain region over which I am defined and it maps to a unique range Position then the result will be that Position. Otherwise BLAST. For example, if I map 1 to 4, 1 to 5, and 2 to 5 (and nothing else), then this method will yield 5 given 2, but BLAST given anything else. To find all the values 1 maps to, use the 'ofAll' operation on the singleton region whose member is 1.

ofAll

public abstract XnRegion ofAll(XnRegion before)

Essential. Transform a region. The result region has exactly those positions which are the mappings of the positions in 'before'. This must be the case even if these positions cannot be enumerated. If the mapping for a given position is multiply defined, then (if that position is in 'before') all position it maps to must be in the result. Because of this property, the behavior of this method must be taken as really defining the nature of a particular mapping (with other method's behavior being defined in terms of this one), despite the fact that it would have been more natural to take Mapping::of(Position *) as the defining behavior.

ofInt

public IntegerValue ofInt(IntegerValue pos)

Unboxed version of 'this->of (xuInteger(pos))'. See discussion in the XuInteger class comment about boxed and unboxed protocols

appliedAfter

public abstract Mapping appliedAfter(Dsp dsp)

Defined by the equivalence: M->transformedBy(D)->of(R) isEqual (M->of(D->of(R))) for all regions R in the domainSpace of M. Equivalent to Dsp::compose, except that it is between a Mapping and a Dsp.

combine

public Mapping combine(Mapping other)

Essential. Result will do both mine and other's mappings. It will do my mapping where I am defined, and it will do the other's where his is defined. If we are both defined over some domain positions, then the result is a multi-valued mapping. If you think of a Mapping simply as a set of pairs (see class comment), then 'combine' yields a Mapping consisting of the union of these two sets.

inverse

public abstract Mapping inverse()

Essential. Return the inverse of this transformation. Considering the Mapping as a set of pairs (see class comment), return the Dsp which has the mirror image of all my pairs.

preCompose

public abstract Mapping preCompose(Dsp dsp)

There is no sensible explanation for what this message does on Mappings which aren't Dsps. In the future, we will probably retire this message, so don't use it.

restrict

public abstract Mapping restrict(XnRegion region)

Essential. Restrict the domain. The domain of the result will be the intersection of my domain and 'region'. Otherwise we are the same.

restrictRange

public abstract Mapping restrictRange(XnRegion region)

Restrict the range. The range of the result will be the intersection of my range and 'region'. Otherwise we are the same.

transformedBy

public abstract Mapping transformedBy(Dsp dsp)

Defined by the equivalence: M->transformedBy(D)->of(R) isEqual (D->of(M->of(R))) for all regions R in the domainSpace of M. Equivalent to Dsp::preCompose, except that it is between a Mapping and a Dsp.

fetchCombine

public abstract Mapping fetchCombine(Mapping mapping)

if I know how to combine the two into a single mapping, then I do so

actualHashForEqual

public int actualHashForEqual()

Description copied from class: Heaper

Defined by subclasses to produce the value returned by hashForEqual.

Overrides:

actualHashForEqual in class Heaper

make

public static Mapping make(CoordinateSpace cs,
                           CoordinateSpace rs)

Make an empty mapping from cs to rs. The domain will consist of an empty region in cs, and the range will consist of an empty region in rs

make

public static Mapping make(CoordinateSpace cs,
                           XnRegion values)

Make a constant mapping from all positions in cs to all positions in values.

make

public static Mapping make(CoordinateSpace cs,
                           CoordinateSpace rs,
                           ImmuSet mappings)

The combine of all the mappings in 'mappings' All domains must be in cs and all ranges in rs. cs and rs must be provided in case 'mappings' is empty.

info

public static void info()

{Mapping CLIENT} combine: other {Mapping} {XuRegion CLIENT} domain {CoordinateSpace CLIENT} domainSpace {Mapping CLIENT} inverse {BooleanVar CLIENT} isComplete {BooleanVar CLIENT} isIdentity {Position CLIENT} of: before {Position} {XuRegion CLIENT} ofAll: before {XuRegion} {XuRegion CLIENT} range {CoordinateSpace CLIENT} rangeSpace {Mapping CLIENT} restrict: region {XuRegion} {Stepper CLIENT of: Mapping} simplerMappings {Mapping CLIENT} unrestricted