Class: QgsUnitTypes

class qgis.core.QgsUnitTypes

Bases: sip.wrapper

Helper functions for various unit types.

Enums

AngleUnit

Bases: enum.IntEnum

AreaUnit

Bases: enum.IntEnum

DistanceUnit

Bases: enum.IntEnum

DistanceUnitType

Bases: enum.IntEnum

LayoutUnit

Bases: enum.IntEnum

LayoutUnitType

Bases: enum.IntEnum

RenderUnit

Bases: enum.IntEnum

SystemOfMeasurement

Bases: enum.IntEnum

TemporalUnit

Bases: enum.IntEnum

UnitType

Bases: enum.IntEnum

VolumeUnit

Bases: enum.IntEnum

Methods

areaToDistanceUnit

Converts an area unit to its corresponding distance unit, e.g., square meters to meters

decodeAngleUnit

Decodes an angular unit from a string.

decodeAreaUnit

Decodes an areal unit from a string.

decodeDistanceUnit

Decodes a distance unit from a string.

decodeLayoutUnit

Decodes a layout unit from a string.

decodeRenderUnit

Decodes a render unit from a string.

decodeTemporalUnit

Decodes a temporal unit from a string.

decodeUnitType

Decodes a unit type from a string.

decodeVolumeUnit

Decodes a volume unit from a string.

distanceToAreaUnit

Converts a distance unit to its corresponding area unit, e.g., meters to square meters

distanceToVolumeUnit

Converts a distance unit to its corresponding volume unit, e.g., meters to cubic meters

encodeUnit

Encodes a distance unit to a string.

encodeUnitType

Encodes a unit type to a string.

formatAngle

Returns an angle formatted as a friendly string.

formatArea

Returns an area formatted as a friendly string.

formatDistance

Returns an distance formatted as a friendly string.

fromUnitToUnitFactor

Returns the conversion factor between the specified distance units.

scaledArea

Will convert an area with a given unit to an area value which is nice to display.

scaledDistance

Will convert a distance with a given unit to a distance value which is nice to display.

stringToAreaUnit

Converts a translated string to an areal unit.

stringToDistanceUnit

Converts a translated string to a distance unit.

stringToTemporalUnit

Converts a translated string to a temporal unit.

stringToVolumeUnit

Converts a translated string to a volume unit.

toAbbreviatedString

Returns a translated abbreviation representing a distance unit.

toString

Returns a translated string representing a distance unit.

unitType

Returns the type for a distance unit.

volumeToDistanceUnit

Converts a volume unit to its corresponding distance unit, e.g., cubic meters to meters

Attributes

staticMetaObject

class AngleUnit(value)

Bases: enum.IntEnum

Units of angles.

Note

Prior to QGIS 3.30 this was available as QgsUnitTypes.AngleUnit.

New in version 3.30.

  • AngleDegrees: Degrees

  • AngleRadians: Square kilometers

  • AngleGon: Gon/gradian

  • AngleMinutesOfArc: Minutes of arc

  • AngleSecondsOfArc: Seconds of arc

  • AngleTurn: Turn/revolutions

  • AngleMilliradiansSI: Angular milliradians (SI definition, 1/1000 of radian)

  • AngleMilNATO: Angular mil (NATO definition, 6400 mil = 2PI radians)

  • AngleUnknownUnit: Unknown angle unit

baseClass

alias of Qgis

class AreaUnit(value)

Bases: enum.IntEnum

Units of area

Note

Prior to QGIS 3.30 this was available as QgsUnitTypes.AreaUnit.

New in version 3.30.

  • AreaSquareMeters: Square meters

  • AreaSquareKilometers: Square kilometers

  • AreaSquareFeet: Square feet

  • AreaSquareYards: Square yards

  • AreaSquareMiles: Square miles

  • AreaHectares: Hectares

  • AreaAcres: Acres

  • AreaSquareNauticalMiles: Square nautical miles

  • AreaSquareDegrees: Square degrees, for planar geographic CRS area measurements

  • AreaSquareCentimeters: Square centimeters

  • AreaSquareMillimeters: Square millimeters

  • SquareInches: Square inches (since QGIS 3.32)

  • AreaUnknownUnit: Unknown areal unit

baseClass

alias of Qgis

class AreaValue
class AreaValue(QgsUnitTypes.AreaValue)

Bases: sip.wrapper

unit
value
class DistanceUnit(value)

Bases: enum.IntEnum

Units of distance

Note

Prior to QGIS 3.30 this was available as QgsUnitTypes.DistanceUnit.

New in version 3.30.

  • DistanceMeters: Meters

  • DistanceKilometers: Kilometers

  • DistanceFeet: Imperial feet

  • DistanceNauticalMiles: Nautical miles

  • DistanceYards: Imperial yards

  • DistanceMiles: Terrestrial miles

  • DistanceDegrees: Degrees, for planar geographic CRS distance measurements

  • DistanceCentimeters: Centimeters

  • DistanceMillimeters: Millimeters

  • Inches: Inches (since QGIS 3.32)

  • DistanceUnknownUnit: Unknown distance unit

baseClass

alias of Qgis

class DistanceUnitType(value)

Bases: enum.IntEnum

Types of distance units

Note

Prior to QGIS 3.30 this was available as QgsUnitTypes.DistanceUnitType.

New in version 3.30.

  • Standard: Unit is a standard measurement unit

  • Geographic: Unit is a geographic (e.g., degree based) unit

  • UnknownType: Unknown unit type

baseClass

alias of Qgis

class DistanceValue
class DistanceValue(QgsUnitTypes.DistanceValue)

Bases: sip.wrapper

unit
value
class LayoutUnit(value)

Bases: enum.IntEnum

Layout measurement units

Note

Prior to QGIS 3.30 this was available as QgsUnitTypes.LayoutUnit.

New in version 3.30.

  • LayoutMillimeters: Millimeters

  • LayoutCentimeters: Centimeters

  • LayoutMeters: Meters

  • LayoutInches: Inches

  • LayoutFeet: Feet

  • LayoutPoints: Typographic points

  • LayoutPicas: Typographic picas

  • LayoutPixels: Pixels

baseClass

alias of Qgis

class LayoutUnitType(value)

Bases: enum.IntEnum

Types of layout units

Note

Prior to QGIS 3.30 this was available as QgsUnitTypes.LayoutUnitType.

New in version 3.30.

  • LayoutPaperUnits: Unit is a paper based measurement unit

  • LayoutScreenUnits: Unit is a screen based measurement unit

baseClass

alias of Qgis

class RenderUnit(value)

Bases: enum.IntEnum

Rendering size units

Note

Prior to QGIS 3.30 this was available as QgsUnitTypes.RenderUnit.

New in version 3.30.

  • RenderMillimeters: Millimeters

  • RenderMapUnits: Map units

  • RenderPixels: Pixels

  • RenderPercentage: Percentage of another measurement (e.g., canvas size, feature size)

  • RenderPoints: Points (e.g., for font sizes)

  • RenderInches: Inches

  • RenderUnknownUnit: Mixed or unknown units

  • RenderMetersInMapUnits: Meters value as Map units

baseClass

alias of Qgis

class SystemOfMeasurement(value)

Bases: enum.IntEnum

Systems of unit measurement.

Note

Prior to QGIS 3.30 this was available as QgsUnitTypes.SystemOfMeasurement.

New in version 3.30.

  • UnknownSystem: Unknown system of measurement

  • MetricSystem: International System of Units (SI)

  • ImperialSystem: British Imperial

  • USCSSystem: United States customary system

baseClass

alias of Qgis

class TemporalUnit(value)

Bases: enum.IntEnum

Temporal units.

Note

Prior to QGIS 3.30 this was available as QgsUnitTypes.TemporalUnit.

New in version 3.30.

  • TemporalMilliseconds: Milliseconds

  • TemporalSeconds: Seconds

  • TemporalMinutes: Minutes

  • TemporalHours: Hours

  • TemporalDays: Days

  • TemporalWeeks: Weeks

  • TemporalMonths: Months

  • TemporalYears: Years

  • TemporalDecades: Decades

  • TemporalCenturies: Centuries

  • TemporalIrregularStep: Special ‘irregular step’ time unit, used for temporal data which uses irregular, non-real-world unit steps (since QGIS 3.20)

  • TemporalUnknownUnit: Unknown time unit

baseClass

alias of Qgis

class UnitType(value)

Bases: enum.IntEnum

Unit types.

Note

Prior to QGIS 3.30 this was available as QgsUnitTypes.UnitType.

New in version 3.30.

  • TypeDistance: Distance unit

  • TypeArea: Area unit

  • TypeVolume: Volume unit

  • TypeUnknown: Unknown unit type

  • TypeTemporal: Temporal unit

baseClass

alias of Qgis

class VolumeUnit(value)

Bases: enum.IntEnum

Units of volume.

Note

Prior to QGIS 3.30 this was available as QgsUnitTypes.VolumeUnit.

New in version 3.30.

  • VolumeCubicMeters: Cubic meters

  • VolumeCubicFeet: Cubic feet

  • VolumeCubicYards: Cubic yards

  • VolumeBarrel: Barrels

  • VolumeCubicDecimeter: Cubic decimeters

  • VolumeLiters: Litres

  • VolumeGallonUS: US Gallons

  • VolumeCubicInch: Cubic inches

  • VolumeCubicCentimeter: Cubic Centimeters

  • VolumeCubicDegrees: Cubic degrees, for planar geographic CRS volume measurements

  • VolumeUnknownUnit: Unknown volume unit

baseClass

alias of Qgis

areaToDistanceUnit(areaUnit: Qgis.AreaUnit) Qgis.DistanceUnit

Converts an area unit to its corresponding distance unit, e.g., square meters to meters

Parameters:

areaUnit (Qgis.AreaUnit) – area unit to convert

Return type:

Qgis.DistanceUnit

Returns:

matching distance unit

New in version 3.10.

decodeAngleUnit(string: str) Tuple[Qgis.AngleUnit, bool]

Decodes an angular unit from a string.

Parameters:

string (str) – string to decode

Return type:

Tuple[Qgis.AngleUnit, bool]

Returns:

  • decoded units

  • ok: boolean, will be set to True if string was converted successfully

See also

encodeUnit()

decodeAreaUnit(string: str) Tuple[Qgis.AreaUnit, bool]

Decodes an areal unit from a string.

Parameters:

string (str) – string to decode

Return type:

Tuple[Qgis.AreaUnit, bool]

Returns:

  • decoded units

  • ok: boolean, will be set to True if string was converted successfully

See also

encodeUnit()

decodeDistanceUnit(string: str) Tuple[Qgis.DistanceUnit, bool]

Decodes a distance unit from a string.

Parameters:

string (str) – string to decode

Return type:

Tuple[Qgis.DistanceUnit, bool]

Returns:

  • decoded units

  • ok: boolean, will be set to True if string was converted successfully

See also

encodeUnit()

decodeLayoutUnit(string: str) Tuple[Qgis.LayoutUnit, bool]

Decodes a layout unit from a string.

Parameters:

string (str) – string to decode

Return type:

Tuple[Qgis.LayoutUnit, bool]

Returns:

  • decoded units

  • ok: boolean, will be set to True if string was converted successfully

See also

encodeUnit()

decodeRenderUnit(string: str) Tuple[Qgis.RenderUnit, bool]

Decodes a render unit from a string.

Parameters:

string (str) – string to decode

Return type:

Tuple[Qgis.RenderUnit, bool]

Returns:

  • decoded units

  • ok: boolean, will be set to True if string was converted successfully

See also

encodeUnit()

decodeTemporalUnit(string: str) Tuple[Qgis.TemporalUnit, bool]

Decodes a temporal unit from a string.

Parameters:

string (str) – string to decode

Return type:

Tuple[Qgis.TemporalUnit, bool]

Returns:

  • decoded units

  • ok: boolean, will be set to True if string was converted successfully

See also

encodeUnit()

New in version 3.14.

decodeUnitType(string: str) Tuple[Qgis.UnitType, bool]

Decodes a unit type from a string.

Parameters:

string (str) – string to decode

Return type:

Tuple[Qgis.UnitType, bool]

Returns:

  • decoded unit type

  • ok: boolean, will be set to True if string was converted successfully

See also

encodeUnitType()

New in version 3.10.

decodeVolumeUnit(string: str) Tuple[Qgis.VolumeUnit, bool]

Decodes a volume unit from a string.

Parameters:

string (str) – string to decode

Return type:

Tuple[Qgis.VolumeUnit, bool]

Returns:

  • decoded units

  • ok: boolean, will be set to True if string was converted successfully

See also

encodeUnit()

New in version 3.10.

distanceToAreaUnit(distanceUnit: Qgis.DistanceUnit) Qgis.AreaUnit

Converts a distance unit to its corresponding area unit, e.g., meters to square meters

Parameters:

distanceUnit (Qgis.DistanceUnit) – distance unit to convert

Return type:

Qgis.AreaUnit

Returns:

matching areal unit

distanceToVolumeUnit(distanceUnit: Qgis.DistanceUnit) Qgis.VolumeUnit

Converts a distance unit to its corresponding volume unit, e.g., meters to cubic meters

Parameters:

distanceUnit (Qgis.DistanceUnit) – distance unit to convert

Return type:

Qgis.VolumeUnit

Returns:

matching volume unit

New in version 3.10.

encodeUnit(unit: Qgis.DistanceUnit) str

Encodes a distance unit to a string.

Parameters:

unit (Qgis.DistanceUnit) – unit to encode

Returns:

encoded string

encodeUnit(unit: Qgis.AreaUnit) -> str Encodes an areal unit to a string.

Parameters:

unit – unit to encode

Returns:

encoded string

See also

decodeAreaUnit()

encodeUnit(unit: Qgis.TemporalUnit) -> str Encodes a temporal unit to a string.

Returns:

encoded string

New in version 3.14.

encodeUnit(unit: Qgis.VolumeUnit) -> str Encodes a volume unit to a string.

Returns:

encoded string

New in version 3.10.

encodeUnit(unit: Qgis.AngleUnit) -> str Encodes an angular unit to a string.

Parameters:

unit – unit to encode

Returns:

encoded string

encodeUnit(unit: Qgis.RenderUnit) -> str Encodes a render unit to a string.

Parameters:

unit – unit to encode

Returns:

encoded string

encodeUnit(unit: Qgis.LayoutUnit) -> str Encodes a layout unit to a string.

Parameters:

unit – unit to encode

Return type:

str

Returns:

encoded string

encodeUnitType(type: Qgis.UnitType) str

Encodes a unit type to a string.

Return type:

str

Returns:

encoded string

See also

decodeUnitType()

New in version 3.10.

Parameters:

type (Qgis.UnitType) –

formatAngle(angle: float, decimals: int, unit: Qgis.AngleUnit) str

Returns an angle formatted as a friendly string.

Parameters:
  • angle (float) – angle to format

  • decimals (int) – number of decimal places to show. A value of -1 indicates that an appropriate number of decimal places should automatically be selected.

  • unit (Qgis.AngleUnit) – unit of angle

Return type:

str

Returns:

formatted angle string

formatArea(area: float, decimals: int, unit: Qgis.AreaUnit, keepBaseUnit: bool = False) str

Returns an area formatted as a friendly string.

Parameters:
  • area (float) – area to format

  • decimals (int) – number of decimal places to show

  • unit (Qgis.AreaUnit) – unit of area

  • keepBaseUnit (bool = False) – set to False to allow conversion of large areas to more suitable units, e.g., square meters to square kilometers

Return type:

str

Returns:

formatted area string

See also

formatDistance()

formatDistance(distance: float, decimals: int, unit: Qgis.DistanceUnit, keepBaseUnit: bool = False) str

Returns an distance formatted as a friendly string.

Parameters:
  • distance (float) – distance to format

  • decimals (int) – number of decimal places to show

  • unit (Qgis.DistanceUnit) – unit of distance

  • keepBaseUnit (bool = False) – set to False to allow conversion of large distances to more suitable units, e.g., meters to kilometers

Return type:

str

Returns:

formatted distance string

See also

formatArea()

fromUnitToUnitFactor(fromUnit: Qgis.DistanceUnit, toUnit: Qgis.DistanceUnit) float

Returns the conversion factor between the specified distance units.

Parameters:
Returns:

multiplication factor to convert between units

fromUnitToUnitFactor(fromUnit: Qgis.AreaUnit, toUnit: Qgis.AreaUnit) -> float Returns the conversion factor between the specified areal units.

Parameters:
  • fromUnit – area unit to convert from

  • toUnit – area unit to convert to

Returns:

multiplication factor to convert between units

fromUnitToUnitFactor(fromUnit: Qgis.TemporalUnit, toUnit: Qgis.TemporalUnit) -> float Returns the conversion factor between the specified temporal units.

Note

Conversion to or from month units assumes a 30 day month length.

Note

Conversion to or from year based units assumes a 365.25 day year length.

Parameters:
  • fromUnit – temporal unit to convert from

  • toUnit – temporal unit to convert to

Returns:

multiplication factor to convert between units

New in version 3.14.

fromUnitToUnitFactor(fromUnit: Qgis.VolumeUnit, toUnit: Qgis.VolumeUnit) -> float Returns the conversion factor between the specified volume units.

Parameters:
  • fromUnit – volume unit to convert from

  • toUnit – volume unit to convert to

Returns:

multiplication factor to convert between units

New in version 3.10.

fromUnitToUnitFactor(fromUnit: Qgis.AngleUnit, toUnit: Qgis.AngleUnit) -> float Returns the conversion factor between the specified angular units.

Parameters:
  • fromUnit – angle unit to convert from

  • toUnit – angle unit to convert to

Return type:

float

Returns:

multiplication factor to convert between units

scaledArea(area: float, unit: Qgis.AreaUnit, decimals: int, keepBaseUnit: bool = False) QgsUnitTypes.AreaValue

Will convert an area with a given unit to an area value which is nice to display. It will convert between different units (e.g. from square meters to square kilometers) if appropriate, unless forced otherwise with keepBaseUnit. The value will also be rounded to decimals (be prepared that the returned value is still a double so it will require further formatting when converting to a string).

Parameters:
  • area (float) –

  • unit (Qgis.AreaUnit) –

  • decimals (int) –

  • keepBaseUnit (bool = False) –

Return type:

QgsUnitTypes.AreaValue

scaledDistance(distance: float, unit: Qgis.DistanceUnit, decimals: int, keepBaseUnit: bool = False) QgsUnitTypes.DistanceValue

Will convert a distance with a given unit to a distance value which is nice to display. It will convert between different units (e.g. from meters to kilometers or millimeters) if appropriate, unless forced otherwise with keepBaseUnit. The value will also be rounded to decimals (be prepared that the returned value is still a double so it will require further formatting when converting to a string).

Parameters:
  • distance (float) –

  • unit (Qgis.DistanceUnit) –

  • decimals (int) –

  • keepBaseUnit (bool = False) –

Return type:

QgsUnitTypes.DistanceValue

staticMetaObject = <PyQt5.QtCore.QMetaObject object>
stringToAreaUnit(string: str) Tuple[Qgis.AreaUnit, bool]

Converts a translated string to an areal unit.

Parameters:

string (str) – string representing an areal unit

Return type:

Tuple[Qgis.AreaUnit, bool]

Returns:

  • the area unit

  • ok: boolean, will be set to True if string was converted successfully

See also

toString()

stringToDistanceUnit(string: str) Tuple[Qgis.DistanceUnit, bool]

Converts a translated string to a distance unit.

Parameters:

string (str) – string representing a distance unit

Return type:

Tuple[Qgis.DistanceUnit, bool]

Returns:

  • the distance unit

  • ok: boolean, will be set to True if string was converted successfully

See also

toString()

stringToTemporalUnit(string: str) Tuple[Qgis.TemporalUnit, bool]

Converts a translated string to a temporal unit.

Parameters:

string (str) – string representing a volume unit

Return type:

Tuple[Qgis.TemporalUnit, bool]

Returns:

  • the temporal unit

  • ok: boolean, will be set to True if string was converted successfully

See also

toString()

New in version 3.14.

stringToVolumeUnit(string: str) Tuple[Qgis.VolumeUnit, bool]

Converts a translated string to a volume unit.

Parameters:

string (str) – string representing a volume unit

Return type:

Tuple[Qgis.VolumeUnit, bool]

Returns:

  • the volume unit

  • ok: boolean, will be set to True if string was converted successfully

See also

toString()

New in version 3.10.

toAbbreviatedString(unit: Qgis.DistanceUnit) str

Returns a translated abbreviation representing a distance unit.

Parameters:

unit (Qgis.DistanceUnit) – unit to convert to string

toAbbreviatedString(unit: Qgis.AreaUnit) -> str Returns a translated abbreviation representing an areal unit.

Parameters:

unit – unit to convert to string

toAbbreviatedString(unit: Qgis.TemporalUnit) -> str Returns a translated abbreviation representing a temporal unit.

New in version 3.14.

toAbbreviatedString(unit: Qgis.VolumeUnit) -> str Returns a translated abbreviation representing a volume unit.

New in version 3.10.

toAbbreviatedString(unit: Qgis.RenderUnit) -> str Returns a translated abbreviation representing a render unit.

Parameters:

unit – unit to convert to string

New in version 3.8.

toAbbreviatedString(unit: Qgis.LayoutUnit) -> str Returns a translated abbreviation representing a layout unit (e.g. “mm”).

Return type:

str

toString(unit: Qgis.DistanceUnit) str

Returns a translated string representing a distance unit.

Parameters:

unit (Qgis.DistanceUnit) – unit to convert to string

toString(unit: Qgis.AreaUnit) -> str Returns a translated string representing an areal unit.

Parameters:

unit – unit to convert to string

toString(unit: Qgis.TemporalUnit) -> str Returns a translated string representing a temporal unit.

New in version 3.14.

toString(unit: Qgis.VolumeUnit) -> str Returns a translated string representing a volume unit.

New in version 3.10.

toString(unit: Qgis.AngleUnit) -> str Returns a translated string representing an angular unit.

Parameters:

unit – unit to convert to string

toString(unit: Qgis.RenderUnit) -> str Returns a translated string representing a render unit.

toString(unit: Qgis.LayoutUnit) -> str Returns a translated string representing a layout unit.

Return type:

str

unitType(unit: Qgis.DistanceUnit) Qgis.DistanceUnitType

Returns the type for a distance unit.

unitType(unit: Qgis.AreaUnit) -> Qgis.DistanceUnitType Returns the type for an areal unit.

unitType(unit: Qgis.VolumeUnit) -> Qgis.DistanceUnitType Returns the type for an volume unit.

New in version 3.10.

unitType(units: Qgis.LayoutUnit) -> Qgis.LayoutUnitType Returns the type for a unit of measurement.

Parameters:

unit (Qgis.DistanceUnit) –

Return type:

Qgis.DistanceUnitType

volumeToDistanceUnit(volumeUnit: Qgis.VolumeUnit) Qgis.DistanceUnit

Converts a volume unit to its corresponding distance unit, e.g., cubic meters to meters

Parameters:

volumeUnit (Qgis.VolumeUnit) – volume unit to convert

Return type:

Qgis.DistanceUnit

Returns:

matching distance unit

New in version 3.10.