Subgroup: other

Class: QgsUnitTypes

class qgis.core.QgsUnitTypes

Bases: sip.wrapper

Helper functions for various unit types.

New in version 2.14: 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.
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.

Signals

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
LayoutCentimeters
LayoutFeet
LayoutInches
LayoutMeters
LayoutMillimeters
LayoutPaperUnits
LayoutPicas
LayoutPixels
LayoutPoints
LayoutScreenUnits
RenderInches
RenderMapUnits
RenderMetersInMapUnits
RenderMillimeters
RenderPercentage
RenderPixels
RenderPoints
RenderUnknownUnit
Standard
UnknownType
AngleDegrees = 0
AngleGon = 2
AngleMinutesOfArc = 3
AngleRadians = 1
AngleSecondsOfArc = 4
AngleTurn = 5
class AngleUnit

Bases: int

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

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

class DistanceUnitType

Bases: int

DistanceUnknownUnit = 9
class DistanceValue

Bases: sip.wrapper

QgsUnitTypes.DistanceValue(QgsUnitTypes.DistanceValue)

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

Bases: int

class LayoutUnitType

Bases: int

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

Bases: int

RenderUnknownUnit = 6
Standard = 0
UnknownType = 2
decodeAngleUnit(string: str) → Tuple[QgsUnitTypes.AngleUnit, bool]

Decodes an angular unit from a string.

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

decoded units

See also

encodeUnit()

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

Decodes an areal unit from a string.

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

decoded units

See also

encodeUnit()

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

Decodes a distance unit from a string.

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

decoded units

See also

encodeUnit()

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

Decodes a layout unit from a string.

Parameters:
  • string – string to decode
  • ok – optional boolean, will be set to true if string was converted successfully
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 – string to decode
  • ok – optional boolean, will be set to true if string was converted successfully
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 – distance unit to convert
Returns:matching areal unit
encodeUnit(unit: QgsUnitTypes.DistanceUnit) → str

Encodes a distance unit to a string.

Parameters:unit – 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
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 – angle to format
  • decimals – number of decimal places to show
  • unit – unit of angle
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 – area to format
  • decimals – number of decimal places to show
  • unit – unit of area
  • keepBaseUnit – set to false to allow conversion of large areas to more suitable units, e.g., square meters to

square kilometers

Returns:formatted area string

New in version 3.0.

See also

formatDistance()

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

Returns an distance formatted as a friendly string.

Parameters:
  • distance – distance to format
  • decimals – number of decimal places to show
  • unit – unit of distance
  • keepBaseUnit – set to false to allow conversion of large distances to more suitable units, e.g., meters to

kilometers

Returns:formatted distance string

New in version 3.0.

See also

formatArea()

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

Returns the conversion factor between the specified distance units.

Parameters:
  • fromUnit – distance unit to convert from
  • toUnit – distance unit to convert to
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
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.

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.

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

Converts a translated string to an areal unit.

Parameters:
  • string – string representing an areal unit
  • ok – optional 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 – string representing a distance unit
  • ok – optional boolean, will be set to true if string was converted successfully

See also

toString()

toAbbreviatedString(unit: QgsUnitTypes.DistanceUnit) → str

Returns a translated abbreviation representing a distance unit.

Parameters:unit – 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.

toString(unit: QgsUnitTypes.DistanceUnit) → str

Returns a translated string representing a distance unit.

Parameters:unit – 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.

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.