.. _vector.miramon:

MiraMon Vector
==============

.. versionadded:: 3.9

.. shortname:: MiraMonVector

.. built_in_by_default::

This driver is capable of translating (reading and writing) structured vectors
of point, arc (*linestrings*), and polygon types from MiraMon vector format.

In MiraMon the concepts of OGRMultiPoints and OGRMultiLineStrings are not supported,
but the driver translates a multipoint into N points and a multistring into N arcs.
When reading a MiraMon file of type *.pol*, the corresponding
layer will be reported as of type wkbPolygon, but depending on the
number of parts of each geometry, the actual type of the geometry for
each feature can be either OGRPolygon or OGRMultiPolygon.

The reading driver verifies if multipart polygons adhere to the
specification (that is to say, the vertices of outer rings should be
oriented clockwise on the X/Y plane, and those of inner rings
counterclockwise). Otherwise, the driver corrects the orientation
(in the original format this specification is not the case as polygon
files are based on topological arc files, where the order of the vertices
may be relevant).

Measures (M coordinate) are not supported.
Symbolization is neither read nor generated by this driver.

A `look-up-table of MiraMon <https://www.miramon.cat/help/eng/mm32/AP6.htm>`__ and
`EPSG <https://epsg.org/home.html>`__ Spatial Reference Systems allows matching
identifiers in both systems.

If a layer contains an old *.rel* format file (used some decades ago),
a warning message will appear explaining how to convert it into a modern *.rel 4* file.

Driver capabilities
-------------------

.. supports_create::

.. supports_georeferencing::

.. supports_virtualio::

Overview of MiraMon format
--------------------------

The MiraMon format is a binary format for vector layer data, linked to
one or more database tables, with or without topology and with rich metadata.
More information about the structured MiraMon vector format is available `on the public
specification <https://www.miramon.cat/new_note/eng/notes/MiraMon_structured_vectors_file_format.pdf>`__.

It is important to keep in mind that a MiraMon vector layer is composed by several files as follows:

To operate with a point layer, you must provide the name with the extension .pnt
(the T.dbf and T.rel files must accompany the .pnt).

To operate with a linestring layer, you must provide the name with the extension .arc
(the A.dbf and A.rel, .nod, N.dbf, and N.rel files must accompany the .arc).

To operate with a polygon layer, you must provide the name with the extension .pol
(the P.dbf, P.rel, A.dbf and A.rel, .nod, N.dbf, and N.rel files must accompany the .pol).

By providing only the main file name, the driver will automatically use the other sidecar files to obtain the
necessary information. In the creation of MiraMon layers, you only need to provide the name
of the main file (with or without extension), and the driver will create the rest of the files.

The following outlines the information contained within each sidecar file:

Preliminary note: *FileName* is, in the following explanations, the first part of the name
of the layer file.

- **Point layers**: These layers contain *point* type features which are described by a single
  coordinate (x,y) or (x, y, z). Each layer is composed by 3 files:

    - *FileName.pnt* file: Contains the geographic database with the coordinates that define the
      point vector features.

    - *FileNameT.dbf* file (note the 'T' before the '.'): Contains the main table of the database
      in dBASE (DBF) format, or in `extended DBF format <https://www.miramon.cat/new_note/eng/notes/DBF_estesa.pdf>`__,
      if necessary. It contains the information (usually alphanumeric, but also file or web links, etc)
      of every feature. The Feature Identifier (FID) field is a field called *ID_GRAFIC* and relates
      every geographical feature to one or more records in the main table.

    - *FileNameT.rel* file (note the 'T' before the '.'): Contains the layer metadata,
      the relational structure of the database (links between the main table and other
      tables [thesauruses, etc] if needed, and the cardinality of the link) and the default
      symbolization description. In the GDAL environment
      only some aspects are documented: the spatial reference system, the language of the
      metadata (English), the extension and a description of the fields.

- **Arc layers**: These layers contain *linestring* type features which are lines
  described by a series of segments, each one defined by coordinates (x, y) or (x, y, z).
  Both extreme vertices of each *linestring* are called nodes. Each layer is composed by 6 files:

    - *FileName.arc* file: Contains the geographic database with the coordinates that define the
      linestring (arc) vector features.

    - *FileNameA.dbf* file (note the 'A' before the '.'): Contains the main table of the database
      in dBASE (DBF) format, or in `extended DBF format <https://www.miramon.cat/new_note/eng/notes/DBF_estesa.pdf>`__,
      if necessary. It contains the information (usually alphanumeric, but also file or web links, etc)
      of every feature. The Feature Identifier (FID) field is a field called *ID_GRAFIC* and relates
      every geographical feature to one or more records in the main table.

    - *FileNameA.rel* file (note the 'A' before the '.'): Contains the layer metadata,
      the relational structure of the database (links between the main table and other
      tables [thesauruses, etc] if needed, and the cardinality of the link) and the default
      symbolization description. In the GDAL environment
      only some aspects are documented: the spatial reference system, the language of the
      metadata (English), the extension and a description of the fields.

    - *FileName.nod* file: Contains the geographic database with information about the
      linestring needed to define each node. It is necessary in the MiraMon vector format but not read by
      the GDAL MiraMon vector driver because nodes contain topological information that is not
      transferred to other formats.

    - *FileNameN.dbf* file (note the 'N' before the '.'): Contains the main table of the database
      in dBASE (DBF) format, or in extended DBF if necessary. This table contains information about
      the relationships between arcs and nodes, and other attributes of the nodes, if needed.
      It is necessary in the MiraMon vector format but not read by the GDAL MiraMon vector driver because
      nodes contain topological information that is not transferred to other formats.

    - *FileNameN.rel* file (note the 'N' before the '.'): Contains the layer metadata,
      the relational structure of the database (links between the main table and other
      tables [thesauruses, etc] if needed, and the cardinality of the link) and the default
      symbolization description. It is necessary in the MiraMon vector format but not read by
      the GDAL MiraMon vector driver because nodes contain topological information that is not
      transferred to other formats.

- **Polygon layers**: These layers contain *polygon* or *multipolygon* type features.
  In MiraMon vector format a polygon is a closed shape described by one or more arcs.
  A polygon can have holes inside it. A polygon can also be linked to other polygons;
  in this case, it is termed a group (*multipolygon*).
  Each layer is composed by 9 files:

    - *FileName.pol* file: Contains the geographic database with information about the linestring
      vector features needed to define the polygon (or multipolygon) vector features.

    - *FileNameP.dbf* file (note the 'P' before the '.'): Contains the main table of the database
      in dBASE (DBF) format, or in `extended DBF format <https://www.miramon.cat/new_note/eng/notes/DBF_estesa.pdf>`__,
      if necessary. It contains the information (usually alphanumeric, but also file or web links, etc)
      of every feature. The Feature Identifier (FID) field is a field called *ID_GRAFIC* and relates
      every geographical feature to one or more records in the main table.

    - *FileNameP.rel* file (note the 'P' before the '.'): Contains the layer metadata,
      the relational structure of the database (links between the main table and other
      tables [thesauruses, etc] if needed, and the cardinality of the link) and the default
      symbolization description. In the GDAL environment
      only some aspects are documented: the spatial reference system, the language of the
      metadata (English), the extension and a description of the fields.

    - *FileName.arc* file: Contains the geographic database with the coordinates that define the
      arc vector features. The polygons within the polygon file reference the arcs in this file by their index.

    - *FileNameA.dbf* file (note the 'A' before the '.'): Contains the main table of the database
      in dBASE (DBF) format, or in extended DBF if necessary. This table contains information about
      the relationship between arcs and polygons, not the main features information. It is necessary in
      MiraMon but not read directly by the GDAL MiraMon vector driver because
      it is redundant to the information on the linestring part.

    - *FileNameA.rel* file (note the 'A' before the '.'): Contains additional data about the data,
      the relations of the database and the symbolization description. It is necessary in
      MiraMon but not read directly by the GDAL MiraMon vector driver.

    - *FileName.nod* file: Contains the geographic database with information about the
      linestring needed to define each node. It is necessary in the MiraMon vector format but not read by
      the GDAL MiraMon vector driver because nodes contain topological information that is not
      transferred to other formats.

    - *FileNameN.dbf* file (note the 'N' before the '.'): Contains the main table of the database
      in dBASE (DBF) format, or in extended DBF if necessary. This table contains information about
      the relationships between arcs and nodes, and other attributes of the nodes, if needed.
      It is necessary in the MiraMon vector format but not read by the GDAL MiraMon vector driver because
      nodes contain topological information that is not transferred to other formats.

    - *FileNameN.rel* file (note the 'N' before the '.'): Contains additional data about the data,
      the relations of the database and the symbolization description. It is necessary in
      MiraMon but not read directly by the GDAL MiraMon vector driver.

Encoding
--------

When reading MiraMon files the code page setting in the header of the .dbf file
is read and used to translate string fields to UTF-8 (regardless of whether they
are in ANSI, OEM or UTF-8).

When writing MiraMon files the codepage of *.dbf* files can be ANSI or UTF8
depending on the layer creation option DBFEncoding.

Creation Issues
---------------

MiraMon can only store one kind of geometry per layer
(points, arcs or polygons). Mixing different kinds of layers
(including raster and geoservices as WMS or WMTS) is possible through MiraMon maps (.mmm).
During creation the driver generates the necessary files to
accommodate each of the three possible types of geometries.
For instance, if a layer or a dataset contains points and arcs,
a set of point files and a set of arc files will be created.

Consequently, during creation the MiraMon vector driver output can be a
folder or a set of files with the appropriate extension (*.pnt*, etc):

- If the output is a **folder**, it will contain all the translated layers with the original name in the origin dataset.

  - In this case a *.mmm* file will be created referencing all layers in the origin dataset to make an
    easy open of the dataset using the MiraMon software.
  - In this case, please specify the MiraMon file output format name using the -f option (**-f MiraMonVector**).

- If the output is a **file** with extension all the translated layers in the origin dataset will be created with the specified name.
  Use this option only when you know that there is only one layer with one feature type in the origin dataset.

The attributes of the MiraMon feature are stored in an associated *.dbf*.
If a classical DBF IV table could not be used (too many fields or records,
large text fields, etc) a file type called extended DBF is used.
This is an improvement of dBASE IV DBF files. The specification of this format can be found in `this file
<https://www.miramon.cat/new_note/eng/notes/DBF_estesa.pdf>`__.

Note that extended *.dbf* files cannot be opened with Excel or
other typical programs. If the complete MiraMon Professional software
is not installed on the computer, the free and standalone
MiraD application can be downloaded from
`this page <https://www.miramon.cat/USA/Prod-MiraD.htm>`__ to open them.

Connection string
-----------------

The MiraMon driver accepts three types of sources of data:

When translating from a MiraMon vector format, the MiraMon vector driver input needs a file with one of the
described extensions:

-  *.pnt* for *points*.
-  *.arc* for *linestrings*.
-  *.pol* for *polygons* (or *multipolygons*).

The extension *.nod* is not valid for translation. Take in consideration all auxiliary files described above.

Field sizes
-----------

The driver will automatically extend string and integer fields to
dynamically accommodate the length of the data to be inserted.

Size Issues
-----------

Geometry: The MiraMon vector format explicitly uses 32-bit offsets in the 1.1 version
and 64-bit offsets in the 2.0 version. It is better to produce 1.1 version files if 2.0
version is not really necessary than always use 2.0 version. Version 1.x files are smaller.

Attributes: The dbf format does not have any offsets in it, so it can be
arbitrarily large.

Open options
------------

The following open options are available.

-  .. oo:: Height
      :choices: First, Lowest, Highest

      Sets which of the possible heights for each vertex is read:
      the *first*, the *lowest* or the *highest* one. It only applies to
      MiraMon multi-height layers, where the same X,Y vertex can have more than one Z.

-  .. oo:: MultiRecordIndex
      :choices: 1, 2, ..., Last, JSON

      In case of fields of type List, if the output driver cannot support them,
      user can select which one wants to keep: *MultiRecordIndex=1* for first, *MultiRecordIndex=2* for second, etc
      and *MultiRecordIndex=last* for the last element of the list.
      *MultiRecordIndex=JSON* option converts the list in a single value in JSON format.
      If not specified, all elements of the list will be translated by default as a OGR list field type.

-  .. oo:: OpenLanguage
      :choices: ENG, CAT, SPA
      :default: ENG

      If the layer to be opened is multilingual (in fact, the *.rel* file), this
      parameter sets the language to be read.


Dataset creation options
------------------------

None

Layer creation options
----------------------

-  .. lco:: Version
      :choices: V1.1, V2.0, last_version
      :default: V1.1

      Version of the file.
      Version 1.1 is limited to an unsigned 32-bit integer for FID, for internal
      offsets and for the number of entities the layer can handle.
      It is the default option.
      Version 2.0 is the 64-bit version. It is practically unlimited
      (unsigned 64-bit integer for FID and internal offsets).
      last_version selects to the last existing version ever.

-  .. lco:: DBFEncoding
      :choices: UTF8, ANSI
      :default: ANSI

      Encoding of the *.dbf* files.
      The MiraMon vector driver can write *.dbf* files in UTF-8 or ANSI charsets.

      As at the moment of this release, UTF-8 tables are not editable in the
      `MiraD application <https://www.miramon.cat/USA/Prod-MiraD.htm>`__, so it
      is recommended to use ANSI instead, if there are no coding problems.

-  .. oo:: CreationLanguage
      :choices: ENG, CAT, SPA
      :default: ENG

      Sets the language used in the metadata file (*.rel*) for the descriptors of
      the *.dbf* fields.

Examples
--------

.. example::

   A translation from an *Example_1.dxf* file with one layer but some different geometric types
   in the layer, will result 'file1.dxf' into a new MiraMon set of layers in the 'output_folder'.

   .. code-block:: bash

      ogr2ogr output_folder Example_1.dxf -f MiraMonVector -lco Version=V1.1


.. example::

   A translation from a *Example_2.dxf* file with one polygon type layer 'file1.dxf' into a new MiraMon layer
   'territories.pol' (with UTF-8 encoding at the *.dbf* files) is performed like this:

   .. code-block:: bash

      ogr2ogr territories.pol Example_2.dxf -lco DBFEncoding=UTF8 (no needed to include **-f MiraMonVector** because the output layer is not a directory)

.. example::

   A translation from a MiraMon layer of arcs, 'rivers.arc', into a new *.gml* file (taking only the first element of
   the multirecords in the attributes table) is performed like this:

   .. code-block:: bash

      ogr2ogr rivers.gml rivers.arc -oo MultiRecordIndex=1

.. example::

   A translation from a MiraMon layer 'tracks.arc' into a new *.gml* file taking the first height of
   every point is performed like this:

   .. code-block:: bash

      ogr2ogr tracks.gml tracks.arc -oo Height=First

.. example::

   A translation from a MiraMon layer 'tracks.arc' into a new *.gml* file taking the last height of
   every point and documenting the attribute descriptors in Catalan (if the layer is multilingual
   and it has this language available) is performed like this:

   .. code-block:: bash

      ogr2ogr tracks.gml tracks.arc -oo Height=First -oo Language=CAT


See Also
--------

-  `MiraMon's vector format specifications <https://www.miramon.cat/new_note/eng/notes/MiraMon_structured_vectors_file_format.pdf>`__
-  `MiraMon Extended DBF format <https://www.miramon.cat/new_note/eng/notes/DBF_estesa.pdf>`__
-  `MiraMon vector layer concepts <https://www.miramon.cat/help/eng/mm32/ap2.htm#structured_vector>`__.
-  `MiraMon page <https://www.miramon.cat/Index_usa.htm>`__
-  `MiraMon help guide <https://www.miramon.cat/help/eng>`__
-  `Grumets research group, the people behind MiraMon <https://www.grumets.cat/index_eng.htm>`__
