CoordSystem
=================

.. currentmodule:: axioma.cs

.. class:: CoordSystem

	Данный класс позволяет производить работу с координатными проекциями

		.. py:attribute:: EARTH_SPHERE_RADIUS

			Радиус сферы

		.. py:attribute:: DEGREES_TO_RADIANS

			Коэффициент пересчета градусов в радианы

		.. py:attribute:: DEGREES_TO_METERS

			Градусы в метры для сферы

		.. py:attribute:: METERS_TO_DEGREES

			Метры в градусы для сферы

		.. py:attribute:: LAT_LON_EPSG

			EPSG для координатной системы Широта/Долгота

		.. py:attribute:: RADIANS_TO_DEGREES

			Коэффициент пересчета радиан в градусы
			
		.. csv-table:: Тип исходных данных при формировании объекта координатной системы :data:`SourceType`:
				:header: "Наименование величины", "Значение", "Описание"

				St_Unknown, 0, "Не определен"
				St_Prj, 1, "Строка MapBasic"
				St_Proj4, 2, "Строка Proj4"
				St_Epsg, 3, "Значение EPSG"
				St_Wkt, 4, "Строка Wkt"

		.. py:method:: forward(p_in, p_out)

			Получение картезианских координат из градусов точки

			:param p_in: входное значение
			:type p_in: :class:`~PyQt5.QtCore.QPointF`
			:param p_out: выходное значение
			:type p_out: :class:`~PyQt5.QtCore.QPointF`
			:return: успешность операции. True выполнено успешно. False преобразование не произведено
			:rtype: :class:`bool`

		.. py:method:: forward(r_in, r_out)

			Получение картезианских координат из градусов rect

			:param r_in: входное значение
			:type r_in: :class:`~PyQt5.QtCore.QRectF`
			:param r_out: выходное значение
			:type r_out: :class:`~PyQt5.QtCore.QRectF`
			:return: успешность операции. True выполнено успешно. False преобразование не произведено
			:rtype: :class:`bool`

		.. py:method:: forward(list_in, list_out)

			Получение картезианских координат из градусов массива точек

			:param list_in: входное значение
			:type list_in: :class:`list` [:class:`~PyQt5.QtCore.QPointF`]
			:param list_out: выходное значение
			:type list_out: :class:`list` [:class:`~PyQt5.QtCore.QPointF`]
			:return: успешность операции. True выполнено успешно. False преобразование не произведено
			:rtype: :class:`bool`

		.. py:method:: inverse(p_in, p_out)

			Получение географических координат (градусов) из картезианских координат для точки

			:param p_in: входное значение
			:type p_in: :class:`~PyQt5.QtCore.QPointF`
			:param p_out: выходное значение
			:type p_out: :class:`~PyQt5.QtCore.QPointF`
			:return: успешность операции. True выполнено успешно. False преобразование не произведено
			:rtype: :class:`bool`

		.. py:method:: inverse(r_in, r_out)

			Получение географических координат (градусов) из картезианских координат для rect

			:param r_in: входное значение
			:type r_in: :class:`~PyQt5.QtCore.QRectF`
			:param r_out: выходное значение
			:type r_out: :class:`~PyQt5.QtCore.QRectF`
			:return: успешность операции. True выполнено успешно. False преобразование не произведено
			:rtype: :class:`bool`

		.. py:method:: inverse(list_in, list_out)

			Получение географических координат (градусов) из картезианских координат для массива точек

			:param list_in: Входное значение
			:type list_in: :class:`list` [:class:`~PyQt5.QtCore.QPointF`]
			:param list_out: Выходное значение
			:type list_out: :class:`list` [:class:`~PyQt5.QtCore.QPointF`]
			:return: Успешность операции. True выполнено успешно. False преобразование не произведено
			:rtype: :class:`bool`

		.. py:method:: clone()

			Клонирует текущую КС

			:return: Копию координатной системы
			:rtype: :class:`~axioma.cs.CoordSystem`

		.. py:method:: unit()

			Единицы измерения в текущей КС

			:return: Единица измерения
			:rtype: :class:`LinearUnit`

		.. py:method:: isEqual(coordSystem)

			Сравнение с другой координатной системой

			:param coordSystem: КС для сравнения
			:type coordSystem: :class:`~axioma.cs.CoordSystem`
			:return: Результат сравнения. True, если эквивалентны
			:rtype: :class:`bool`

		.. py:method:: isLatLong()

			Является ли данная КС широтой/долготой

			:return: True, если да
			:rtype: :class:`bool`

		.. py:method:: proj4Str()

			Формирует строку формата `proj4 <https://github.com/OSGeo/proj.4>`_

			:return: Строка proj4 или пустая строка если аналога не найдено
			:rtype: :class:`str`

		.. py:method:: PRJStr()

			Формирует строку формата MapBasic

			:return: Строка prj или пустая строка если аналога не найдено
			:rtype: :class:`str`

		.. py:method:: epsg()

			Пробует найти номер `EPSG <http://www.epsg.org>`_. Сначала ищем в описании проекции PRJ файла, затем пробуем использовать алгоритмы OGR, и наконец, ищем соответствие в файле epsg.xml

			:return:  Соответствующее проекции значение EPSG. -1 если соответствующей не найдено
			:rtype: :class:`int`

		.. py:method:: exportToWKT()

			Экспорт в формат WKT

			:return: Строка WKT или пустая строка если аналога не найдено
			:rtype: :class:`str`

		.. py:method:: setDescription(description)

			Задание описания координатной системы

			:param description: Описание координатной системы
			:type description: :class:`str`

		.. py:method:: description()

			Описание координатной системы

			:return: Описание координатной системы
			:rtype: :class:`str`

		.. py:method:: cartesianDistance(point_1, point_2)

			Расчет расстояния между двумя точками в текущей проекции

			:param point_1: первая точка
			:type point_1: :class:`~PyQt5.QtCore.QPointF`
			:param point_2: вторая точка
			:type point_2: :class:`~PyQt5.QtCore.QPointF`
			:return: расстояние между точками
			:rtype: :class:`float`

		.. py:method:: sphericalDistance(point_1, point_2)

			Расчет расстояния между двумя точками на сфере

			:param point_1: первая точка
			:type point_1: :class:`~PyQt5.QtCore.QPointF`
			:param point_2: вторая точка
			:type point_2: :class:`~PyQt5.QtCore.QPointF`
			:return: расстояние между точками, успешность операции
			:rtype: :class:`float`, :class:`bool`

		.. py:method:: isNonEarth()

			Является ли данная КС декартовой

			:return: True, если да
			:rtype: :class:`bool`

		.. py:method:: rectNumericCoordSys()

			Возвращает MBR для КС

			:return: Прямоугольник для данной КС  в случае успешного выполнения или пустой QRectF
			:rtype: :class:`~PyQt5.QtCore.QRectF`
			
		.. py:method:: setRectCoordSystem(rect)

			Установка нового ограничивающего прямоугольника для проекции

			:param rect: Новое значение прямоугольника
			:type rect: :class:`~PyQt5.QtCore.QRectF`

		.. py:staticmethod:: testEqual(cs1, cs2)

			Сравнение двух координатных систем

			:param cs1: Первая КС для сравнения
			:type cs1: :class:`~axioma.cs.CoordSystem`
			:param cs2: Вторая КС для сравнения
			:type cs2: :class:`~axioma.cs.CoordSystem`
			:return: Результат сравнения. True, если эквивалентны
			:rtype: :class:`bool`

		.. py:method:: affineTransform()

			Возвращает матрицу афинного преобразования, если таковая имеется

			:return: Матрица афинного преобразования
			:rtype: :class:`~PyQt5.QtGui.QTransform`

		.. py:method:: setAffineTransform(value)

			Установка нового значения матрицы преобразования для проекции

			:param value: Матрица
			:type value: :class:`~PyQt5.QtGui.QTransform`

		.. py:method:: getSemiMajor()

			Большая полуось эллипсоида

			:return: Размер большой полуоси
			:rtype: :class:`float`

		.. py:method:: getSemiMinor()

			Малая полуось эллипсоида

			:return: Размер малой полуоси
			:rtype: :class:`float`

		.. py:method:: getInvFlattening()

			Коэффициент сжатия эллипсоида

			:return: Значение коэффициента
			:rtype: :class:`float`

		.. py:method:: getTOWGS84Params()

			Коэффициенты преобразования датума к WGS84

			:return: Коэффициенты. Если получить невозможно, возникает ошибка.
			:rtype: :class:`list` [ :class:`str` ]
			
		..

			.. class:: SourceData

				Описывает источник, на базе которого была создана координатная система

				.. py:attribute:: type

				Тип источника

				:type: :data:`SourceType`

				.. py:attribute:: string

				Исходные данные при формировании координатной системы

				:type: :class:`str`


		.. py:method:: sourceData()

			Данные, которые использовались при создании данной координатной системы

			:rtype: :class:`SourceData`

Пример использования:
  
  .. code-block:: python
  
    from axioma.cs import *
    from PyQt5.QtCore import *

    cs_latlon = CoordSysFactory.defaultCoordSysFactory().createFromEPSG(4326)
    cs_merc = CoordSysFactory.defaultCoordSysFactory().createFromPRJ("Earth Projection 12, 62, \"m\", 0")

    # forward / inverse
    if cs_latlon is not None:
        p_out = QPointF()
        p_in = QPointF(45.0, 45.0)
        res = cs_latlon.forward(p_in, p_out)
        if res:
            print ("Forward (%f, %f) res=%r" % (p_out.x(), p_out.y(), res))
        p_out1= QPointF()
        res = cs_latlon.inverse(p_out, p_out1)
        if res:
            print ("Inverse (%f, %f) res=%r" % (p_out1.x(), p_out1.y(), res))

    #rect
    rect = cs_merc.rectNumericCoordSys();
    print ("Rect of CoordSystem: (%.1f %.1f) (%.1f %.1f)" % (rect.left(), rect.top(), rect.right(), rect.bottom()))

    #distance
    print( "Cartesian distance %f" % cs_latlon.cartesianDistance(QPointF(0.0, 0.0), QPointF(45.0, 45.0)))
    sd = cs_latlon.sphericalDistance(QPointF(0.0, 0.0), QPointF(45.0, 45.0))
    print( "Spherical distance %f (success=%r)" % (sd[0], sd[1]))

    #compare
    print ("Compare CoordSystems: %r %r" % ( cs_latlon.isEqual(cs_merc), cs_latlon.isEqual(cs_latlon)))

    # export
    print( cs_latlon.PRJStr())
    print( cs_latlon.proj4Str())
    print( cs_latlon.exportToWKT())