gws.lib.uom

Units of measure.

Conversions between map scales and resolutions, between millimetres and pixels, and parsing of values with units.

Values with units are represented as tuples, see the gws.Uom* types:

  • gws.UomValue: (5, gws.Uom.mm),

  • gws.UomPoint and gws.UomSize: (10, 20, gws.Uom.mm),

  • gws.UomExtent: (0, 0, 100, 200, gws.Uom.mm).

Conversions between millimetres and pixels need a resolution in pixels per inch. Scale and resolution conversions use the OGC standard pixel size of 0.28 mm.

Example:

import gws.lib.uom

v = gws.lib.uom.parse('5mm')  # (5.0, gws.Uom.mm)
gws.lib.uom.to_px(v, 96)  # (18.89..., gws.Uom.px)
gws.lib.uom.to_str(v)  # '5mm'
gws.lib.uom.parse_point('10mm,20mm')  # (10.0, 20.0, gws.Uom.mm)
gws.lib.uom.res_to_scale(0.28)  # 1000

Source code: gws.lib.uom

Package Contents

gws.lib.uom.DEFAULT_PRECISION
gws.lib.uom.MM_PER_IN = 25.4

Conversion factor from inch to millimetre.

gws.lib.uom.mm_to_px(x: _number, ppi: int) → float

Convert millimetres to pixels.

Parameters:

  • x – Millimetres.

  • ppi – Pixels per inch.

Returns:

Number of pixels.

gws.lib.uom.OGC_M_PER_PX = 0.00028

1px = 0.28mm).

Type:

OGC meter per pixel (OGC 06-042, 7.2.4.6.9

gws.lib.uom.OGC_SCREEN_PPI = 90.71428571428572

Screen pixels per inch according to the OGC standard pixel size.

gws.lib.uom.parse(val: str | int | float | tuple | list, default_unit: gws.Uom = None) → gws.UomValue

Parse a value with a unit.

Parameters:

  • val – A string like '5mm', a number, or a pair like [5, 'mm'].

  • default_unit – Unit for numbers and for strings without a known unit.

Returns:

The value with its unit.

Raises:

ValueError – If the format is invalid, or the unit is missing or unknown and there is no default unit.

gws.lib.uom.parse_extent(val: str | tuple | list) → gws.UomExtent

Parse an extent with a unit.

Parameters:

val – A comma-separated string like '1mm,2mm,3mm,4mm', a list of four strings, or a list like [1, 2, 3, 4, 'mm'].

Returns:

The extent with its unit.

Raises:

ValueError – If the extent is invalid or the units differ.

gws.lib.uom.parse_point(val: str | tuple | list) → gws.UomPoint

Parse a point with a unit.

Parameters:

val – A comma-separated string like '1mm,2mm', a list like ['1mm', '2mm'] or a list like [1, 2, 'mm'].

Returns:

The point with its unit.

Raises:

ValueError – If the point is invalid or the units differ.

gws.lib.uom.PDF_DPI = 96

Dots per inch in a PDF file.

gws.lib.uom.PT_PER_IN = 72

Conversion factor from inch to points.

gws.lib.uom.px_to_mm(x: _number, ppi: int) → float

Convert pixels to millimetres.

Parameters:

  • x – Number of pixels.

  • ppi – Pixels per inch.

Returns:

Millimetres.

gws.lib.uom.res_to_scale(x: _number) → int

Convert a resolution to a scale denominator.

Parameters:

x – Resolution in metres per pixel.

Returns:

Scale denominator, using the OGC pixel size.

gws.lib.uom.scale_to_res(x: _number) → float

Convert a scale denominator to a resolution.

Parameters:

x – Scale denominator.

Returns:

Resolution in metres per pixel, using the OGC pixel size.

gws.lib.uom.size_mm_to_px(xy: gws.Size, ppi: int) → gws.Size

Convert a size in millimetres to pixels.

Parameters:

  • xy – Size in millimetres.

  • ppi – Pixels per inch.

Returns:

Size in pixels.

gws.lib.uom.size_px_to_mm(xy: gws.Size, ppi: int) → gws.Size

Convert a size in pixels to millimetres.

Parameters:

  • xy – Size in pixels.

  • ppi – Pixels per inch.

Returns:

Size in millimetres.

gws.lib.uom.size_to_mm(xyu: gws.UomSize, ppi: int) → gws.UomSize

Convert a size with a unit to millimetres.

Parameters:

  • xyu – Size in mm or px.

  • ppi – Pixels per inch.

Returns:

Size in millimetres.

Raises:

ValueError – If the unit is not mm or px.

gws.lib.uom.size_to_px(xyu: gws.UomSize, ppi: int) → gws.UomSize

Convert a size with a unit to pixels.

Parameters:

  • xyu – Size in px or mm.

  • ppi – Pixels per inch.

Returns:

Size in pixels.

Raises:

ValueError – If the unit is not px or mm.

gws.lib.uom.to_mm(xu: gws.UomValue, ppi: int) → gws.UomValue

Convert a value with a unit to millimetres.

Parameters:

  • xu – Value in mm or px.

  • ppi – Pixels per inch.

Returns:

The value in millimetres.

Raises:

ValueError – If the unit is not mm or px.

gws.lib.uom.to_px(xu: gws.UomValue, ppi: int) → gws.UomValue

Convert a value with a unit to pixels.

Parameters:

  • xu – Value in px or mm.

  • ppi – Pixels per inch.

Returns:

The value in pixels.

Raises:

ValueError – If the unit is not px or mm.

gws.lib.uom.to_str(xu: gws.UomValue) → str

Convert a value with a unit to a string.

Whole numbers are written without a decimal part.

Parameters:

xu – Value with a unit.

Returns:

A string like 5mm.