Class: QgsUnitTypes

class qgis.core.QgsUnitTypes

Bases: sip.wrapper

Helper functions for various unit types.

New in version 2.14:

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

AngleDegrees

AngleGon

AngleMilNATO

AngleMilliradiansSI

AngleMinutesOfArc

AngleRadians

AngleSecondsOfArc

AngleTurn

AngleUnknownUnit

AreaAcres

AreaHectares

AreaSquareCentimeters

AreaSquareDegrees

AreaSquareFeet

AreaSquareKilometers

AreaSquareMeters

AreaSquareMiles

AreaSquareMillimeters

AreaSquareNauticalMiles

AreaSquareYards

AreaUnknownUnit

DistanceCentimeters

DistanceDegrees

DistanceFeet

DistanceKilometers

DistanceMeters

DistanceMiles

DistanceMillimeters

DistanceNauticalMiles

DistanceUnknownUnit

DistanceYards

Geographic

ImperialSystem

LayoutCentimeters

LayoutFeet

LayoutInches

LayoutMeters

LayoutMillimeters

LayoutPaperUnits

LayoutPicas

LayoutPixels

LayoutPoints

LayoutScreenUnits

MetricSystem

RenderInches

RenderMapUnits

RenderMetersInMapUnits

RenderMillimeters

RenderPercentage

RenderPixels

RenderPoints

RenderUnknownUnit

Standard

TemporalCenturies

TemporalDays

TemporalDecades

TemporalHours

TemporalMilliseconds

TemporalMinutes

TemporalMonths

TemporalSeconds

TemporalUnknownUnit

TemporalWeeks

TemporalYears

TypeArea

TypeDistance

TypeTemporal

TypeUnknown

TypeVolume

USCSSystem

UnknownSystem

UnknownType

VolumeBarrel

VolumeCubicCentimeter

VolumeCubicDecimeter

VolumeCubicDegrees

VolumeCubicFeet

VolumeCubicInch

VolumeCubicMeters

VolumeCubicYards

VolumeGallonUS

VolumeLiters

VolumeUnknownUnit

staticMetaObject

AngleDegrees = 0
AngleGon = 2
AngleMilNATO = 7
AngleMilliradiansSI = 6
AngleMinutesOfArc = 3
AngleRadians = 1
AngleSecondsOfArc = 4
AngleTurn = 5
class AngleUnit

Bases: int

baseClass

alias of qgis._core.QgsUnitTypes

AngleUnknownUnit = 8
AreaAcres = 6
AreaHectares = 5
AreaSquareCentimeters = 9
AreaSquareDegrees = 8
AreaSquareFeet = 2
AreaSquareKilometers = 1
AreaSquareMeters = 0
AreaSquareMiles = 4
AreaSquareMillimeters = 10
AreaSquareNauticalMiles = 7
AreaSquareYards = 3
class AreaUnit

Bases: int

baseClass

alias of qgis._core.QgsUnitTypes

AreaUnknownUnit = 11
class AreaValue
class AreaValue(QgsUnitTypes.AreaValue) None

Bases: sip.wrapper

unit
value
DistanceCentimeters = 7
DistanceDegrees = 6
DistanceFeet = 2
DistanceKilometers = 1
DistanceMeters = 0
DistanceMiles = 5
DistanceMillimeters = 8
DistanceNauticalMiles = 3
class DistanceUnit

Bases: int

baseClass

alias of qgis._core.QgsUnitTypes

class DistanceUnitType

Bases: int

DistanceUnknownUnit = 9
class DistanceValue
class DistanceValue(QgsUnitTypes.DistanceValue) None

Bases: sip.wrapper

unit
value
DistanceYards = 4
Geographic = 1
ImperialSystem = 2
LayoutCentimeters = 1
LayoutFeet = 4
LayoutInches = 3
LayoutMeters = 2
LayoutMillimeters = 0
LayoutPaperUnits = 0
LayoutPicas = 6
LayoutPixels = 7
LayoutPoints = 5
LayoutScreenUnits = 1
class LayoutUnit

Bases: int

baseClass

alias of qgis._core.QgsUnitTypes

class LayoutUnitType

Bases: int

MetricSystem = 1
RenderInches = 5
RenderMapUnits = 1
RenderMetersInMapUnits = 7
RenderMillimeters = 0
RenderPercentage = 3
RenderPixels = 2
RenderPoints = 4
class RenderUnit

Bases: int

baseClass

alias of qgis._core.QgsUnitTypes

RenderUnknownUnit = 6
Standard = 0
class SystemOfMeasurement

Bases: int

baseClass

alias of qgis._core.QgsUnitTypes

TemporalCenturies = 9
TemporalDays = 4
TemporalDecades = 8
TemporalHours = 3
TemporalMilliseconds = 0
TemporalMinutes = 2
TemporalMonths = 6
TemporalSeconds = 1
class TemporalUnit

Bases: int

baseClass

alias of qgis._core.QgsUnitTypes

TemporalUnknownUnit = 10
TemporalWeeks = 5
TemporalYears = 7
TypeArea = 1
TypeDistance = 0
TypeTemporal = 4
TypeUnknown = 3
TypeVolume = 2
USCSSystem = 3
class UnitType

Bases: int

UnknownSystem = 0
UnknownType = 2
VolumeBarrel = 3
VolumeCubicCentimeter = 8
VolumeCubicDecimeter = 4
VolumeCubicDegrees = 9
VolumeCubicFeet = 1
VolumeCubicInch = 7
VolumeCubicMeters = 0
VolumeCubicYards = 2
VolumeGallonUS = 6
VolumeLiters = 5
class VolumeUnit

Bases: int

baseClass

alias of qgis._core.QgsUnitTypes

VolumeUnknownUnit = 10
areaToDistanceUnit(areaUnit: QgsUnitTypes.AreaUnit) QgsUnitTypes.DistanceUnit

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

Parameters

areaUnit (QgsUnitTypes.AreaUnit) – area unit to convert

Return type

QgsUnitTypes.DistanceUnit

Returns

matching distance unit

New in version 3.10.

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

Decodes an angular unit from a string.

Parameters

string (str) – string to decode

Return type

Tuple[QgsUnitTypes.AngleUnit, bool]

Returns

  • decoded units

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

See also

encodeUnit()

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

Decodes an areal unit from a string.

Parameters

string (str) – string to decode

Return type

Tuple[QgsUnitTypes.AreaUnit, bool]

Returns

  • decoded units

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

See also

encodeUnit()

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

Decodes a distance unit from a string.

Parameters

string (str) – string to decode

Return type

Tuple[QgsUnitTypes.DistanceUnit, bool]

Returns

  • decoded units

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

See also

encodeUnit()

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

Decodes a layout unit from a string.

Parameters

string (str) – string to decode

Return type

Tuple[QgsUnitTypes.LayoutUnit, bool]

Returns

  • decoded units

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

See also

encodeUnit()

New in version 3.0.

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

Decodes a render unit from a string.

Parameters

string (str) – string to decode

Return type

Tuple[QgsUnitTypes.RenderUnit, bool]

Returns

  • decoded units

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

See also

encodeUnit()

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

Decodes a temporal unit from a string.

Parameters

string (str) – string to decode

Return type

Tuple[QgsUnitTypes.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[QgsUnitTypes.UnitType, bool]

Decodes a unit type from a string.

Parameters

string (str) – string to decode

Return type

Tuple[QgsUnitTypes.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[QgsUnitTypes.VolumeUnit, bool]

Decodes a volume unit from a string.

Parameters

string (str) – string to decode

Return type

Tuple[QgsUnitTypes.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: QgsUnitTypes.DistanceUnit) QgsUnitTypes.AreaUnit

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

Parameters

distanceUnit (QgsUnitTypes.DistanceUnit) – distance unit to convert

Return type

QgsUnitTypes.AreaUnit

Returns

matching areal unit

distanceToVolumeUnit(distanceUnit: QgsUnitTypes.DistanceUnit) QgsUnitTypes.VolumeUnit

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

Parameters

distanceUnit (QgsUnitTypes.DistanceUnit) – distance unit to convert

Return type

QgsUnitTypes.VolumeUnit

Returns

matching volume unit

New in version 3.10.

encodeUnit(unit: QgsUnitTypes.DistanceUnit) str

Encodes a distance unit to a string.

Parameters

unit (QgsUnitTypes.DistanceUnit) – unit to encode

Returns

encoded string

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

Parameters

unit – unit to encode

Returns

encoded string

See also

decodeAreaUnit()

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

Returns

encoded string

New in version 3.14.

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

Returns

encoded string

New in version 3.10.

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

Parameters

unit – unit to encode

Returns

encoded string

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

Parameters

unit – unit to encode

Returns

encoded string

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

Parameters

unit – unit to encode

Return type

str

Returns

encoded string

New in version 3.0.

encodeUnitType(type: QgsUnitTypes.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 (QgsUnitTypes.UnitType) –

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

Returns an angle formatted as a friendly string.

Parameters
  • angle (float) – angle to format

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

  • unit (QgsUnitTypes.AngleUnit) – unit of angle

Return type

str

Returns

formatted angle string

formatArea(area: float, decimals: int, unit: QgsUnitTypes.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 (QgsUnitTypes.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()

New in version 3.0.

formatDistance(distance: float, decimals: int, unit: QgsUnitTypes.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 (QgsUnitTypes.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()

New in version 3.0.

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

Returns the conversion factor between the specified distance units.

Parameters
Returns

multiplication factor to convert between units

fromUnitToUnitFactor(fromUnit: QgsUnitTypes.AreaUnit, toUnit: QgsUnitTypes.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: QgsUnitTypes.TemporalUnit, toUnit: QgsUnitTypes.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: QgsUnitTypes.VolumeUnit, toUnit: QgsUnitTypes.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: QgsUnitTypes.AngleUnit, toUnit: QgsUnitTypes.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: QgsUnitTypes.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).

New in version 3.0.

Parameters
Return type

QgsUnitTypes.AreaValue

scaledDistance(distance: float, unit: QgsUnitTypes.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).

New in version 3.0.

Parameters
Return type

QgsUnitTypes.DistanceValue

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

Converts a translated string to an areal unit.

Parameters

string (str) – string representing an areal unit

Return type

Tuple[QgsUnitTypes.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[QgsUnitTypes.DistanceUnit, bool]

Converts a translated string to a distance unit.

Parameters

string (str) – string representing a distance unit

Return type

Tuple[QgsUnitTypes.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[QgsUnitTypes.TemporalUnit, bool]

Converts a translated string to a temporal unit.

Parameters

string (str) – string representing a volume unit

Return type

Tuple[QgsUnitTypes.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[QgsUnitTypes.VolumeUnit, bool]

Converts a translated string to a volume unit.

Parameters

string (str) – string representing a volume unit

Return type

Tuple[QgsUnitTypes.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: QgsUnitTypes.DistanceUnit) str

Returns a translated abbreviation representing a distance unit.

Parameters

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

New in version 3.0.

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

Parameters

unit – unit to convert to string

New in version 3.0.

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

New in version 3.14.

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

New in version 3.10.

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

Parameters

unit – unit to convert to string

New in version 3.8.

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

New in version 3.0.

Return type

str

toString(unit: QgsUnitTypes.DistanceUnit) str

Returns a translated string representing a distance unit.

Parameters

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

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

Parameters

unit – unit to convert to string

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

New in version 3.14.

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

New in version 3.10.

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

Parameters

unit – unit to convert to string

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

New in version 3.0.

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

New in version 3.0.

Return type

str

unitType(unit: QgsUnitTypes.DistanceUnit) QgsUnitTypes.DistanceUnitType

Returns the type for a distance unit.

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

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

New in version 3.10.

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

New in version 3.0.

Parameters

unit (QgsUnitTypes.DistanceUnit) –

Return type

QgsUnitTypes.DistanceUnitType

volumeToDistanceUnit(volumeUnit: QgsUnitTypes.VolumeUnit) QgsUnitTypes.DistanceUnit

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

Parameters

volumeUnit (QgsUnitTypes.VolumeUnit) – volume unit to convert

Return type

QgsUnitTypes.DistanceUnit

Returns

matching distance unit

New in version 3.10.