# Map - Карта

class axipy.Map

  Класс карты. Рассматривается как группа слоев, объединенная в единую сущность. Вне зависимости от СК входящих в карту слоев, карта отображает все слои в одной СК. Найти наиболее подходящую для этого можно с помощью `get_best_coordsystem()` или же установить другую.

  Единицы измерения расстояний `distanceUnit` и площадей `areaUnit` берутся из настроек по умолчанию.

  Параметры:

    - layers – Список слоев, с которым будет создана карта.

    - preserve_order – Порядок слоев оставить как есть, в противном случае будет произведена попытка отсортировать слои в соответствии с контентом (растры вниз, точечные объекты наверх)

  Исключение:

    ValueError – Если один и тот же слой был передан несколько раз.

  Пример.

      table_world = provider_manager.openfile(filepath)
      world = Layer.create(table_world)
      map = Map([world])
      print('СК:', map.get_best_coordsystem().prj)
      print('Охват:', map.get_best_rect())
      print('Единицы измерения расстояний:', map.distanceUnit.description)
      map.distanceUnit = Unit.mi
      print('Единицы измерения расстояний (изменено):', map.distanceUnit.description)
      '''
      >>> СК: Earth Projection 12, 62, "m", 0
      >>> Охват: (-16194966.287183324 -8621185.324024437) (16789976.633236416 8326222.646170927)
      >>> Единицы измерения расстояний: километры
      >>> Единицы измерения расстояний (изменено): мили
      '''

  Свойства:

  `areaUnit` | Устанавливает или возвращает единицы измерения площадей карты.
  `cosmetic` | Возвращает косметический слой карты.
  `custom_labels` | Возвращает пользовательские метки.
  `distanceUnit` | Устанавливает или возвращает единицы измерения расстояний на карте.
  `editable_layer` | Устанавливает или возвращает редактируемый слой для текущей карты.
  `layers` | Возвращает список слоев и групп слоев.

  Методы:

  `draw`(context) | Рисует карту в контексте.
  `draw_vector`(context) | Рисует карту в контексте в виде вектора.
  `get_best_coordsystem`() | Определяет координатную системы карты, наиболее подходящую исходя из содержимого перечня слоев.
  `get_best_rect`([coordsystem]) | Определяет ограничивающий прямоугольник карты.
  `to_image`(width, height[, coordsystem, bbox]) | Рисует карту в изображение.

  Сигналы:

  `need_redraw` | Сигнал о необходимости перерисовки карты.

  Специальные методы:

  `__contains__`(layer) | Проверяет наличие элемента в объекте (оператор `in`).
  `__eq__`(other) | Оператор равенства (==).
  `__str__`() | Неформальное строковое представление объекта при вызове `str` или `print()`.

  __contains__(layer: Layer) → bool

    Проверяет наличие элемента в объекте (оператор `in`).

  __eq__(other: object) → bool

    Оператор равенства (==).

  __str__() → str

    Неформальное строковое представление объекта при вызове `str` или `print()`.

  property areaUnit: AreaUnit

    Устанавливает или возвращает единицы измерения площадей карты.

  property cosmetic: CosmeticLayer

    Возвращает косметический слой карты.

  property custom_labels: CustomLabels

    Возвращает пользовательские метки.

    Пример.

        table_world = provider_manager.openfile(filepath)
        world_layer = Layer.create(table_world)
        map_ = Map([world_layer])
        layer = map_.layers[0]
        # Определим свойства
        p = CustomLabelProperties()
        # Переназначим выражение
        p.expression = 'Новое выражение'
        # Угол поворота
        p.angle = 30
        # Выноска будет в виде стрелки
        p.endType = CustomLabelEndType.Arrow
        # Положение выноски
        p.position = Point(100, 200)
        # Выравнивание относительно этого положения
        p.position_align = LabelLayoutPosition.TopRight
        # Устанавливаем стиль выноски
        p.arrow_style = Style.from_mapinfo('Pen (2, 86, 16711680)')
        # Устанавливаем стиль текста для метки
        text_style = TextStyle("Droid Sans", 12)
        text_style.color = Qt.red
        text_style.bold = True
        p.text_style = text_style
        # Установим свойства
        map_.custom_labels.set(layer, 1, p)
        # Запрос свойств
        props = map_.custom_labels.get(layer, 1)
        # Перечень идентификаторов объектов с метками
        ids = map_.custom_labels.ids(layer)
        # Установка параметров по умолчанию для новых меток
        s = Style.from_mapinfo('Pen (2, 86, 16711680)')
        map_.custom_labels.set_default_arrow_type(layer, s)
        map_.custom_labels.set_default_end_type(layer, CustomLabelEndType.Line)

  property distanceUnit: LinearUnit

    Устанавливает или возвращает единицы измерения расстояний на карте.

  draw(context: Context)

    Рисует карту в контексте.

    Параметры:

      context – Контекст рисования.

    Пример получения карты как растра.

        in_filepath = 'world.tab'
        table_world = provider_manager.openfile(in_filepath)
        m = Map([table_world])
        image = QImage(1600, 1000, QImage.Format_ARGB32_Premultiplied)
        image.fill(Qt.transparent)
        painter = QPainter(image)
        context = Context(painter)
        m.draw(context)
        out_filepath = 'world.png'
        image.save(out_filepath)

  draw_vector(context: Context)

    Рисует карту в контексте в виде вектора. Это может потребоваться при генерации карты в виде, к примеру, SVG.

    Параметры:

      context – Контекст рисования.

    Пример получения карты в виде вектора.

        in_filepath = 'world.tab'
        out_filepath = 'world.svg'
        table_world = provider_manager.openfile(in_filepath)
        m = Map([table_world])
        generator = QSvgGenerator()
        generator.setFileName(out_filepath)
        generator.setSize(QSize(1600,1000));
        painter_svg = QPainter(generator)
        context = Context(painter_svg)
        m.draw_vector(context)

  property editable_layer: Optional[VectorLayer]

    Устанавливает или возвращает редактируемый слой для текущей карты.

    Исключение:

      ValueError – При попытке установить слой, не принадлежащий этой карте.

  get_best_coordsystem() → CoordSystem

    Определяет координатную системы карты, наиболее подходящую исходя из содержимого перечня слоев.

  get_best_rect(coordsystem: Optional[CoordSystem] = None) → Rect

    Определяет ограничивающий прямоугольник карты.

    Параметры:

      coordsystem – Координатная система, в которой необходимо получить результат. Если отсутствует, будет выдан результат для наиболее подходящей координатной системы.

  property layers: ListLayers

    Возвращает список слоев и групп слоев.

    Примечание

    Не содержит косметический слой `cosmetic`.

    Примеры доступа.

        # Создадим карту с тремя слоями
        map = Map([world, worldcap, russia])
        print(len(map.layers))
        '''
        >>> 3
        '''
        print(map.layers[0].title)
        '''
        >>> world
        '''
        # Группировка первый двух слоев с именем "Мир"
        map.layers.group([0, 1], 'Мир')
        # Перечень элементов
        for l in map.layers:
            if isinstance(l, Layer):
                print('Слой:', l.title)
            elif isinstance(l, ListLayers):
                print('Группа:', l.title)
        '''
        >>> Группа: Мир
        >>> Слой: russia
        '''
        # Изменение позиции
        map.layers.move(0, 1)
        # Управление видимостью группы слоев
        map.layers[1].visible = False
        # Разгруппировка ранее созданной группы
        map.layers.ungroup(1)
        # Удаление слоя из карты
        map.layers.remove(1)
        # Добавление пустой группы
        map.layers.add_group('Новая группа')

  property need_redraw: Signal

    Сигнал о необходимости перерисовки карты. Возникает при изменении контента одного или нескольких слоев карты. Это может быть обусловлено изменением данных таблиц.

    Тип результата:

      Signal[]

    Пример.

        # Смотрим активное окно.
        if isinstance(view_manager.active, MapView):
            # Если это карта, подключимся к событию обновления окна этой карты.
            map_view = view_manager.active
            map_view.map.need_redraw.connect(lambda: print('Update map'))

  to_image(width: int, height: int, coordsystem: Optional[CoordSystem] = None, bbox: Optional[Rect] = None) → QImage

    Рисует карту в изображение.

    Параметры:

      - width – Ширина выходного изображения.

      - height – Высота выходного изображения.

      - coordsystem – Координатная система. Если не задана, берется наиболее подходящая.

      - bbox – Ограничивающий прямоугольник. Если не задан, берется у карты.

    Результат:

      Изображение.