TotalDepth.util.plot.Coord (Plot Coordinates)¶

Main Classes¶

Most classes in this module are collections.namedtuple objects.

Class	Description	Attributes
`Dim`	Linear dimension	value units
`Box`	A Box	width depth
`Pad`	Padding around a tree object	prev next, parent child
`Margin`	Padding around an object	left right top bottom
`Pt`	A point in Cartesian space	x y

Reference¶

Provides a fairly basic two dimensional coordinate system.

exception TotalDepth.util.plot.Coord.ExceptionCoord¶: Exception class for representing Coordinates.

exception TotalDepth.util.plot.Coord.ExceptionCoordUnitConvert¶: Exception raised when converting units.

TotalDepth.util.plot.Coord.BASE_UNITS = 'px'¶: Base units for dimensions

TotalDepth.util.plot.Coord.UNIT_MAP = {None: 1.0, 'px': 1.0, 'pt': 1.0, 'pc': 12.0, 'in': 72.0, 'cm': 28.346456692913385, 'mm': 2.834645669291339}¶: Map of {unit name : conversion factor to base units, …}

TotalDepth.util.plot.Coord.exactConversion(units_a, units_b='px')¶: Returns True it the two dimension can be converted exactly. This is the case where the units are the same or the factors are exact multiples.

TotalDepth.util.plot.Coord.UNIT_MAP_DEFAULT_FORMAT = {None: '%.4f', 'px': '%d', 'pt': '%d', 'pc': '%.2f', 'cm': '%.2f', 'mm': '%.1f', 'in': '%.3f', 'm': '%.4f', 'ft': '%.4f', 'NM': '%.6f'}¶: Formatting strings for writing attributes. We are trying not to write 3.999999999mm here!

TotalDepth.util.plot.Coord.UNIT_MAP_DEFAULT_FORMAT_WITH_UNITS = {None: '%.4f%s', 'px': '%d%s', 'pt': '%d%s', 'pc': '%.2f%s', 'cm': '%.2f%s', 'mm': '%.1f%s', 'in': '%.3f%s', 'm': '%.4f%s', 'ft': '%.4f%s', 'NM': '%.6f%s'}¶: Map of formatting strings for value and units e.g. to create ‘0.667in’ from (2.0 / 3.0, ‘in’)

TotalDepth.util.plot.Coord.units()¶: Returns the unsorted list of acceptable units.

TotalDepth.util.plot.Coord.convert(val, unitFrom, unitTo)¶: Convert a value from one set of units to another.

class TotalDepth.util.plot.Coord.Dim¶

Represents a dimension as an engineering value i.e. a number and units.

scale(factor)¶: Returns a new Dim() multiplied by a factor, units are unchanged.

divide(factor)¶: Returns a new Dim() divided by a factor, units are unchanged.

convert(u)¶: Returns a new Dim() with units changed and value converted.

__str__()¶: Return str(self).

__repr__()¶: Return a nicely formatted representation string

__format__(format_spec)¶: Default object formatter.

__add__(other)¶: Overload self+other, returned result has the sum of self and other. The units chosen are self’s unless self’s units are None in which case other’s units are used (if not None).

__sub__(other)¶: Overload self-other, returned result has the difference of self and other. The units chosen are self’s unless self’s units are None in which case other’s units are used (if not None).

__iadd__(other)¶: Addition in place, value of other is converted to my units and added.

__isub__(other)¶: Subtraction in place, value of other is subtracted.

__mul__(other)¶: Multiply by a factor that is a number.

__truediv__(other)¶: Divide by a factor that is a number.

__imul__(other)¶: Indirect multiply by a factor that is a number.

__itruediv__(other)¶: Indirect divide by a factor that is a number.

__lt__(other)¶: Return self<value.

__le__(other)¶: Return self<=value.

__eq__(other)¶: Return self==value.

__ne__(other)¶: Return self!=value.

__gt__(other)¶: Return self>value.

__ge__(other)¶: Return self>=value.

TotalDepth.util.plot.Coord.dimIn(v)¶: Returns a Dim object with the value in inches.

class TotalDepth.util.plot.Coord.Box¶

__str__()¶: Return str(self).

__repr__()¶: Return a nicely formatted representation string

__format__(format_spec)¶: Default object formatter.

class TotalDepth.util.plot.Coord.Pad¶

Padding around another object that forms the Bounding Box. All 4 attributes are Dim() objects

__str__()¶: Return str(self).

__repr__()¶: Return a nicely formatted representation string

__format__(format_spec)¶: Default object formatter.

class TotalDepth.util.plot.Coord.Margin¶

Margin padding around another object. All 4 attributes are Coord.Dim() objects.

__str__()¶: Return str(self).

__repr__()¶: Return a nicely formatted representation string

__format__(format_spec)¶: Default object formatter.

class TotalDepth.util.plot.Coord.Pt¶

A point, an absolute x/y position on the plot area. Members are Coord.Dim().

__eq__(other)¶: Comparison.

__str__()¶: Return str(self).

__repr__()¶: Return a nicely formatted representation string

__format__(format_spec)¶: Default object formatter.

convert(u)¶: Returns a new Pt() with units changed and value converted.

scale(factor)¶: Returns a new Pt() scaled by a factor, units are unchanged.

normalise_units(units=None)¶: Returns a point with both x and y with the same units. If units is given then x and y will be in those units. This may return self or a new point.

TotalDepth.util.plot.Coord.to_cartesian(origin: TotalDepth.util.plot.Coord.Pt, radius: TotalDepth.util.plot.Coord.Dim, angle: float) → TotalDepth.util.plot.Coord.Pt¶: Displaces a point by radius in direction angle in radians which is an x to y rotation. dx is cos(angle) and dy is sin(angle). For example in a SVG coordinate system where +x is right and +y down an angle of less than pi/2 will move the point to the right and down. For use in a mapping system where +x is northing/Latitude N and +y easting/Longitude E an angle of less then pi/2 will move the point up and to the right.

TotalDepth.util.plot.Coord.to_polar(pt_from: TotalDepth.util.plot.Coord.Pt, pt_to: TotalDepth.util.plot.Coord.Pt) → Tuple[TotalDepth.util.plot.Coord.Dim, float]¶

Returns a radius as a Dim and angle in radians. NOTE: This uses math.atan2() so returns the result is between -pi and pi.

Will raise if the given points are identical.

TotalDepth.util.plot.Coord.baseUnitsDim(theLen)¶

Returns a Coord.Dim() of length and units BASE_UNITS.

Parameters:	theLen (`float, int`) – Length.
Returns:	`cpip.plot.Coord.Dim([float, str])` – A new dimension of theLen in base units.

TotalDepth.util.plot.Coord.zeroBaseUnitsDim()¶

Returns a Coord.Dim() of zero length and units BASE_UNITS.

Returns:	`cpip.plot.Coord.Dim([float, str])` – A new dimension of zero.

TotalDepth.util.plot.Coord.zeroBaseUnitsBox()¶: Returns a Coord.Box() of zero dimensions and units BASE_UNITS.

TotalDepth.util.plot.Coord.zeroBaseUnitsPad()¶: Returns a Coord.Pad() of zero dimensions and units BASE_UNITS.

TotalDepth.util.plot.Coord.zeroBaseUnitsPt()¶

Returns a Coord.Dim() of zero length and units BASE_UNITS.

Returns:	`cpip.plot.Coord.Pt([cpip.plot.Coord.Dim([float, str]), cpip.plot.Coord.Dim([float, str])])` – A new point with the values [0, 0].

TotalDepth.util.plot.Coord.pxUnitsDim(theLen)¶

Returns a Coord.Dim() of length and units ‘px’.

Parameters:	theLen (`float, int`) – Length.
Returns:	`cpip.plot.Coord.Dim([float, str])` – A new dimension of theLen in base units.

TotalDepth.util.plot.Coord.pxBaseUnitsDim()¶

Returns a Coord.Dim() of zero length and units ‘px’.

Returns:	`cpip.plot.Coord.Dim([float, str])` – A new dimension of zero.

TotalDepth.util.plot.Coord.pxBaseUnitsBox()¶: Returns a Coord.Box() of zero dimensions and units ‘px’.

TotalDepth.util.plot.Coord.pxBaseUnitsPad()¶: Returns a Coord.Pad() of zero dimensions and units ‘px’.

TotalDepth.util.plot.Coord.pxBaseUnitsPt()¶

Returns a Coord.Dim() of zero length and units ‘px’.

Returns:	`cpip.plot.Coord.Pt([cpip.plot.Coord.Dim([float, str]), cpip.plot.Coord.Dim([float, str])])` – A new point with the values [0, 0].

TotalDepth.util.plot.Coord.newPt(theP, incX=None, incY=None)¶

Returns a new Pt object by incrementing existing point incX, incY that are both Dim() objects or None.

Parameters:

theP (cpip.plot.Coord.Pt([cpip.plot.Coord.Dim([float, str]), cpip.plot.Coord.Pt([cpip.plot.Coord.Dim([float, str])])) – The initial point.
incX (NoneType, cpip.plot.Coord.Dim([float, str]), cpip.plot.Coord.Dim([int, str])) – Distance to move in the x axis.
incY (NoneType, cpip.plot.Coord.Dim([float, str]), cpip.plot.Coord.Dim([int, str])) – Distance to move in the y axis.

Returns:

cpip.plot.Coord.Pt([cpip.plot.Coord.Dim([float, str]), cpip.plot.Coord.Dim([float, str])]) – The new point.

TotalDepth.util.plot.Coord.convertPt(theP, theUnits)¶

Returns a new point with the dimensions of theP converted to theUnits.

TODO: Deprecate this.

TotalDepth.util.plot.Coord.mirrorPt(start: TotalDepth.util.plot.Coord.Pt, finish: TotalDepth.util.plot.Coord.Pt) → TotalDepth.util.plot.Coord.Pt¶: Returns a new point that is the mirror of the finish point, 180 degrees from start to finish.

Examples¶

`Coord.Dim()`¶

Creation, addition and subtraction:

d = Coord.Dim(1, 'in') + Coord.Dim(18, 'px')
# d is 1.25 inches
d = Coord.Dim(1, 'in') - Coord.Dim(18, 'px')
# d is 0.75 inches
d += Coord.Dim(25.4, 'mm')
# d is 1.75 inches

Scaling and unit conversion returns a new object:

a = Coord.Dim(12, 'px')
b = myObj.scale(6.0)
# b is 72 pixels
c = b.convert('in')
# 1 is 1 inch

Comparison:

assert(Coord.Dim(1, 'in') == Coord.Dim(72, 'px'))
assert(Coord.Dim(1, 'in') >= Coord.Dim(72, 'px'))
assert(Coord.Dim(1, 'in') <= Coord.Dim(72, 'px'))
assert(Coord.Dim(1, 'in') > Coord.Dim(71, 'px'))
assert(Coord.Dim(1, 'in') < Coord.Dim(73, 'px'))

`Coord.Pt()`¶

Creation:

p = Coord.Pt(
        Coord.Dim(12, 'px'),
        Coord.Dim(24, 'px'),
        )
print(p)
# Prints: 'Pt(x=Dim(12px), y=Dim(24px))'
p.x # Coord.Dim(12, 'px'))
p.y # Coord.Dim(24, 'px'))
# Scale up by 6 and convert units
pIn = p.scale(6).convert('in')
# pIn now 'Pt(x=Dim(1in), y=Dim(2in))'

Testing¶

The unit tests are in test/TestCoord.py.