Class: QgsUnitTypes

class qgis.core.QgsUnitTypes

Bases: sip.wrapper

Helper functions for various unit types.

Methods

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.

distanceToAreaUnit

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

encodeUnit

Encodes a distance unit 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.

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.

Attributes

AngleDegrees

AngleGon

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

USCSSystem

UnknownSystem

UnknownType

staticMetaObject

AngleDegrees = 0
AngleGon = 2
AngleMinutesOfArc = 3
AngleRadians = 1
AngleSecondsOfArc = 4
AngleTurn = 5
class AngleUnit

Bases: int

baseClass

alias of QgsUnitTypes

AngleUnknownUnit = 6
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 QgsUnitTypes

AreaUnknownUnit = 11
class AreaValue

Bases: sip.wrapper

QgsUnitTypes.AreaValue(QgsUnitTypes.AreaValue)

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 QgsUnitTypes

class DistanceUnitType

Bases: int

DistanceUnknownUnit = 9
class DistanceValue

Bases: sip.wrapper

QgsUnitTypes.DistanceValue(QgsUnitTypes.DistanceValue)

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

RenderUnknownUnit = 6
Standard = 0
class SystemOfMeasurement

Bases: int

baseClass

alias of QgsUnitTypes

USCSSystem = 3
UnknownSystem = 0
UnknownType = 2
decodeAngleUnit(string: str) → Tuple[QgsUnitTypes.AngleUnit, bool]

Decodes an angular unit from a string.

Parameters
  • string (str) – string to decode

  • ok – optional boolean, will be set to true if string was converted successfully

Return type

Tuple[QgsUnitTypes.AngleUnit, bool]

Returns

decoded units

See also

encodeUnit()

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

Decodes an areal unit from a string.

Parameters
  • string (str) – string to decode

  • ok – optional boolean, will be set to true if string was converted successfully

Return type

Tuple[QgsUnitTypes.AreaUnit, bool]

Returns

decoded units

See also

encodeUnit()

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

Decodes a distance unit from a string.

Parameters
  • string (str) – string to decode

  • ok – optional boolean, will be set to true if string was converted successfully

Return type

Tuple[QgsUnitTypes.DistanceUnit, bool]

Returns

decoded units

See also

encodeUnit()

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

Decodes a layout unit from a string.

Parameters
  • string (str) – string to decode

  • ok – optional boolean, will be set to true if string was converted successfully

Return type

Tuple[QgsUnitTypes.LayoutUnit, bool]

Returns

decoded units

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

  • ok – optional boolean, will be set to true if string was converted successfully

Return type

Tuple[QgsUnitTypes.RenderUnit, bool]

Returns

decoded units

See also

encodeUnit()

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

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

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

  • ok – optional boolean, will be set to true if string was converted successfully

See also

toString()

Return type

Tuple[QgsUnitTypes.AreaUnit, bool]

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

Converts a translated string to a distance unit.

Parameters
  • string (str) – string representing a distance unit

  • ok – optional boolean, will be set to true if string was converted successfully

See also

toString()

Return type

Tuple[QgsUnitTypes.DistanceUnit, bool]

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