Units

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.ExceptionUnitsMissmatchedCategory

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

exception TotalDepth.LIS.core.Units.ExceptionUnitsNoUnitInCategory

When a unit does not exist in a category.

exception TotalDepth.LIS.core.Units.ExceptionUnitsUnknownCategory

When a unit category does not exist.

exception TotalDepth.LIS.core.Units.ExceptionUnitsUnknownUnit

When a unit does not exist.

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.

convert(val, other)

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

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.

convert(v, u_1, u_2)

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

unitConvertor(u)

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

units()

Reuturns a list of unit names for this category.

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.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.hasUnit(u)

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

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

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

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.

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.retUnitConvert(u)

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

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

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

TotalDepth.LIS.core.Units.unitCategories()

Returns a list of the unit categories.

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.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.

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.