TotalDepth.LIS.core.Units (Unit Conversion)

Provides unit conversion for LIS79.

The __RAW_UNIT_MAP is the master map from which all other data is derived. Its format is as follows:

key - The unit category as four bytes representing uppercase ASCII characters. value - A tuple of three fields:

  • [0] - Descriptive string of the unit category.

  • [1] - The base unit name as four bytes representing uppercase ASCII characters.

  • [2] - A tuple the contents of which is a four or five item tuple:

    • If four members:
      • [2][0] - The unit name as four bytes representing uppercase ASCII characters.
      • [2][1] - The multiplier as a float.
      • [2][2] - Descriptive string of the units.
      • [2][3] - The unit name that this is an alternate for as four bytes
        representing uppercase ASCII characters, or four spaces.
    • If five members:
      • [2][0] - The unit name as four bytes representing uppercase ASCII characters.
      • [2][1] - The multiplier as a float.
      • [2][2] - The offset as a float.
      • [2][3] - Descriptive string of the units.
      • [2][4] - The unit name that this is an alternate for as four bytes
        representing uppercase ASCII characters or four spaces.

The unit name should also be unique.

TODO: Clean up units by making reciprocal e.g. 1/6.0 rather than 0.166666…

TODO: Check each unit for errors.

exception TotalDepth.LIS.core.Units.ExceptionUnits

Specialisation of exception for Unit conversion.

exception TotalDepth.LIS.core.Units.ExceptionUnitsUnknownUnit

When a unit does not exist.

exception TotalDepth.LIS.core.Units.ExceptionUnitsUnknownCategory

When a unit category does not exist.

exception TotalDepth.LIS.core.Units.ExceptionUnitsNoUnitInCategory

When a unit does not exist in a category.

exception TotalDepth.LIS.core.Units.ExceptionUnitsMissmatchedCategory

When a two units do not exist in the same category.

class TotalDepth.LIS.core.Units.UnitConvertCategory(theCat, theDesc, theBaseUnitName, theUnitS)

Internal module data structure that represents a category of units such as linear length.

theCat is the unit category.

theDesc is the description of that category.

theBaseUnitName is the name of the base units for the category. For example for linear lenght this is b’M ‘.

theUnitS is a list of unit names.

__init__(theCat, theDesc, theBaseUnitName, theUnitS)

Initialize self. See help(type(self)) for accurate signature.

units()

Reuturns a list of unit names for this category.

unitConvertor(u)

Returns a UnitConvert object corresponding to the name u. Will raise a ExceptionUnitsNoUnitInCategory if not found.

convert(v, u_1, u_2)

Returns a value converted from one units to another. e.g. convert(1.2, “FEET”, “INCH”)

__weakref__

list of weak references to the object (if defined)

class TotalDepth.LIS.core.Units.UnitConvert(tup)

Internal data structure for this module that representas a particular unit of measure. Takes a 4 or 5 member tuple from __RAW_UNIT_MAP.

__init__(tup)

Initialize self. See help(type(self)) for accurate signature.

convert(val, other)

Convert a value from me to the other where other is a UnitConvert object.

__weakref__

list of weak references to the object (if defined)

TotalDepth.LIS.core.Units.unitCategories()

Returns a list of the unit categories.

TotalDepth.LIS.core.Units.hasUnitCategory(c)

Returns True if I have that unit category e.g. b”TIME”.

TotalDepth.LIS.core.Units.hasUnit(u)

Returns True if I have that unit e,g, b”FEET”.

TotalDepth.LIS.core.Units.category(unit)

Returns the category of the unit. May raise a ExceptionUnitsUnknownUnit.

TotalDepth.LIS.core.Units.categoryDescription(theCat)

Returns the description of a unit category.

TotalDepth.LIS.core.Units.units(theCat=None)

Returns an unordered list of unit names. If category is None all unit names are returned, otherwise the unit names for a particular category are returned. This may raise a ExceptionUnitsUnknownCategory if the category does not exist.

TotalDepth.LIS.core.Units.retUnitConvertCategory(c)

Returns a UnitConvertCategory object for the category. May raise a ExceptionUnits or descendent.

TotalDepth.LIS.core.Units.retUnitConvert(u)

Returns a UnitConvert object for the unit. May raise a ExceptionUnits or descendent.

TotalDepth.LIS.core.Units.unitDescription(u)

Returns the description of the unit. e.g. Given “.1IN” returns “Tenth-inches”. May raise a ExceptionUnits or descendent.

TotalDepth.LIS.core.Units.realUnitName(u)

Returns the real unit name or None if u is the ‘real’ unit e.g. the ‘real’ unit name for b”FT ” is b”FEET”. May raise a ExceptionUnits or descendent.

TotalDepth.LIS.core.Units.convert(v, u_1, u_2)

Returns a value converted from one units to another. e.g. convert(1.2, b”FEET”, b”INCH”).

Will raise an ExceptionUnitsUnknownUnit if either unit is unknown.

Will raise an ExceptionUnitsMissmatchedCategory is both units doe not belong is the same unit category.

TotalDepth.LIS.core.Units.opticalUnits(u)

If possible returns the ‘optical’ units i.e. user friendly units. For example the ‘optical’ units of b’.1IN’ are b’FEET’. Failure returns the argument.

Examples

Converting bytes objects:

from TotalDepth.LIS.core import Units

v = Units.convert(1.0, b"M   ", b"FEET")
# v is now 3.281

Testing

The unit tests are in test/TestUnits.py.