Add Ground Control Points
=========================

Geoxarray allows writing Ground Control Points (GCPs) to an Xarray
DataArray or Dataset. If possible it is recommended to write 1D
coordinate arrays (see :doc:`coordinates`), but this requires
data to be uniformly spaced. For more information on coordinates
see the :doc:`../topics/coordinates` documentation.

GCPs used with Geoxarray must be formatted as GeoJSON in a normal Python
``str`` object.

.. testcode::

   import xarray as xr
   import numpy as np
   import geoxarray

   gcp_data = """{'type': 'FeatureCollection', 'features': [
       {'type': 'Feature', 'properties': {'id': '1', 'info': '', 'row': 0.0, 'col': 0.0},
        'geometry': {'type': 'Point', 'coordinates': [33.03, 61.80, 126.43]}},
       {'type': 'Feature', 'properties': {'id': '2', 'info': '', 'row': 0.0, 'col': 530.0},
        'geometry': {'type': 'Point', 'coordinates': [32.64, 61.85, 126.43]}},
       {'type': 'Feature', 'properties': {'id': '3', 'info': '', 'row': 0.0, 'col': 1060.0},
        'geometry': {'type': 'Point', 'coordinates': [32.25, 61.90, 126.43]}},
       {'type': 'Feature', 'properties': {'id': '4', 'info': '', 'row': 0.0, 'col': 1590.0},
        'geometry': {'type': 'Point', 'coordinates': [31.86, 61.95, 126.43]}},
       {'type': 'Feature', 'properties': {'id': '5', 'info': '', 'row': 0.0, 'col': 2120.0},
        'geometry': {'type': 'Point', 'coordinates': [31.47, 62.00, 126.43]}},
       {'type': 'Feature', 'properties': {'id': '6', 'info': '', 'row': 0.0, 'col': 2650.0},
        'geometry': {'type': 'Point', 'coordinates': [31.08, 62.04, 126.43]}},
       {'type': 'Feature', 'properties': {'id': '7', 'info': '', 'row': 0.0, 'col': 3180.0},
        'geometry': {'type': 'Point', 'coordinates': [30.68, 62.09, 126.43]}}]}"""
   my_data_arr = xr.DataArray(
       np.zeros((20, 10)),
       dims=("y", "x"),
        coords={},
   )
   new_data_arr = my_data_arr.geo.write_gcps(gcp_data)
   print(new_data_arr.geo.gcps)

Which will give you the GCP GeoJSON back:

.. testoutput::

    {'type': 'FeatureCollection', 'features': [
        {'type': 'Feature', 'properties': {'id': '1', 'info': '', 'row': 0.0, 'col': 0.0},
         'geometry': {'type': 'Point', 'coordinates': [33.03, 61.80, 126.43]}},
        {'type': 'Feature', 'properties': {'id': '2', 'info': '', 'row': 0.0, 'col': 530.0},
         'geometry': {'type': 'Point', 'coordinates': [32.64, 61.85, 126.43]}},
        {'type': 'Feature', 'properties': {'id': '3', 'info': '', 'row': 0.0, 'col': 1060.0},
         'geometry': {'type': 'Point', 'coordinates': [32.25, 61.90, 126.43]}},
        {'type': 'Feature', 'properties': {'id': '4', 'info': '', 'row': 0.0, 'col': 1590.0},
         'geometry': {'type': 'Point', 'coordinates': [31.86, 61.95, 126.43]}},
        {'type': 'Feature', 'properties': {'id': '5', 'info': '', 'row': 0.0, 'col': 2120.0},
         'geometry': {'type': 'Point', 'coordinates': [31.47, 62.00, 126.43]}},
        {'type': 'Feature', 'properties': {'id': '6', 'info': '', 'row': 0.0, 'col': 2650.0},
         'geometry': {'type': 'Point', 'coordinates': [31.08, 62.04, 126.43]}},
        {'type': 'Feature', 'properties': {'id': '7', 'info': '', 'row': 0.0, 'col': 3180.0},
         'geometry': {'type': 'Point', 'coordinates': [30.68, 62.09, 126.43]}}]}