FGDC Metadata
=============

The FGDCMetadata object uses the gis-metadata-parser library to expose *and* format FGDC compliant metadata. The FGDCMetadata object makes data accessible in a homogenized way. An added complexity with FGDC metadata is that metadata are stored in (likely nested) XML. Therefore, using this data container requires a bit of data introspection before getting started.

Projections
-----------
Handling projections in an arbitrary way is challenging because FGDC metadata contains a <mapproj> key that then contains a map projection name (<mapprojn) and an arbitrary set of projection parameters. For this library, we ask that the user either fully define the projection fields in the FGDC template or allow this library to handle it. What does that mean?

If the user wishes to define the projection fully, they should provide an input template that contains all of the necessary fields (see the [FGDC specification] (https://www.fgdc.gov/metadata/csdgm-standard)):

.. code-block:: xml
  
  <mapproj>
    <mapprojn>Equirectangular</mapprojn>
    <equirect>
      <stdparll></stdparll>
      <longcm></longcm>
      <feast></feast>
      <fnorth></fnorth>
    </equirect>
  </mapproj>

When specifying the projection using this method, this library will provide the values for each key.

Alternatively, the user can supply a keyword argument when reading an FGDC template and specify the name of the projection to be used. The fields and values will then be autogenerated on serialization.

.. code-block:: python

  fgdc = FGDCMetadata('kaguyatc_dtm_template.xml', proj='orthogr')

Supported projections are:
  - 'orthogr' - orthographic
  - 'equirect' - equirectangular
  - 'polatsr' - polar stereographic

Warnings, Caveats, and TODOs
----------------------------
FGDC metadata are hard. Right now, the library does not support writing the FGDC metadata in the canonical ordering. In other words, the order of the top-level keys on write out will not be the same as an input template. We are working to determine how best to handle this as validation of the FGDC metadata results in warnings. We note that these are not errors and the resulting metadata is FGDC compliant, but it is still concerning to see warning on validation. Also, we expose (and extend) the fields exposed by the gis-metadata-parser project. We are working to support additional fields in a seamless way (such as robust provider support for each of the different areas a provider can be specified.) Again, the FGDC metadata generated by this library is compliant. It is not as complete as we would like in instances where data, such as provider, come from a source other than an input template. So in practice, if your input template specifies fields that we do not support, the fields are maintained. If you are hoping to parse that data from another source into FGDC XML, we are not quite there yet.