Merge pull request #1656 from CartoDB/josema/ch85336/improve-docs-abo…

…ut-crs

Doc, changes, example and test for raising errors about CRSs

cartoframes/io/carto.py

@@ -6,7 +6,7 @@
 from carto.exceptions import CartoException
 
 from .managers.context_manager import ContextManager
-from ..utils.geom_utils import set_geometry, has_geometry
+from ..utils.geom_utils import check_crs, has_geometry, set_geometry
 from ..utils.logger import log
 from ..utils.utils import is_valid_str, is_sql_query
 from ..utils.metrics import send_metrics
@@ -65,7 +65,7 @@ def read_carto(source, credentials=None, limit=None, retry_times=3, schema=None,
 @send_metrics('data_uploaded')
 def to_carto(dataframe, table_name, credentials=None, if_exists='fail', geom_col=None, index=False, index_label=None,
              cartodbfy=True, log_enabled=True):
-    """Upload a DataFrame to CARTO.
+    """Upload a DataFrame to CARTO. The geometry's CRS must be WGS 84 (EPSG:4326) so you can use it on CARTO.
 
     Args:
         dataframe (pandas.DataFrame, geopandas.GeoDataFrame`): data to be uploaded.
@@ -90,6 +90,9 @@ def to_carto(dataframe, table_name, credentials=None, if_exists='fail', geom_col
     if not isinstance(dataframe, DataFrame):
         raise ValueError('Wrong dataframe. You should provide a valid DataFrame instance.')
 
+    if isinstance(dataframe, GeoDataFrame):
+        check_crs(dataframe)
+
     if not is_valid_str(table_name):
         raise ValueError('Wrong table name. You should provide a valid table name.')
 

cartoframes/utils/geom_utils.py

@@ -253,3 +253,20 @@ def to_geojson(geom, buffer_simplify=True):
             ), sort_keys=True)
         else:
             return json.dumps(shapely.geometry.mapping(geom), sort_keys=True)
+
+
+def check_crs(gdf):
+    current_crs = get_crs(gdf)
+    expected_crs = 'epsg:4326'
+    if current_crs is not None and current_crs != expected_crs:
+        raise ValueError('No valid geometry CRS "{}", it must be "{}".'.format(current_crs, expected_crs))
+
+
+def get_crs(gdf):
+    if gdf.crs is None:
+        return None
+
+    if type(gdf.crs) == dict:
+        return gdf.crs['init']
+    else:
+        return str(gdf.crs)

cartoframes/viz/layer.py

@@ -22,7 +22,7 @@ class Layer:
 
     Args:
         source (str, pandas.DataFrame, geopandas.GeoDataFrame): The source data:
-            table name, SQL query or a dataframe.
+            table name, SQL query or a dataframe. If dataframe, the geometry's CRS must be WGS 84 (EPSG:4326).
         style (dict, or :py:class:`Style <cartoframes.viz.style.Style>`, optional):
             The style of the visualization.
         legends (bool, :py:class:`Legend <cartoframes.viz.legend.Legend>` list, optional):

cartoframes/viz/source.py

@@ -2,7 +2,7 @@
 from geopandas import GeoDataFrame
 
 from ..io.managers.context_manager import ContextManager
-from ..utils.geom_utils import set_geometry, has_geometry
+from ..utils.geom_utils import check_crs, has_geometry, set_geometry
 from ..utils.utils import get_geodataframe_data, get_geodataframe_bounds, \
                           get_geodataframe_geom_type, get_datetime_column_names
 
@@ -75,6 +75,9 @@ def __init__(self, source, credentials=None, geom_col=None, encode_data=True):
             self.query = self.manager.compute_query(source)
             self.credentials = self.manager.credentials
         elif isinstance(source, DataFrame):
+            if isinstance(source, GeoDataFrame):
+                check_crs(source)
+
             # DataFrame, GeoDataFrame
             self.type = SourceType.GEOJSON
             self.gdf = GeoDataFrame(source, copy=True)

docs/developer-center/examples/examples.json

@@ -38,6 +38,11 @@
             "desc": "Load data from a CARTO table using a SQL Query",
             "file": "load_data_from_carto_query",
             "path": "data_management"
+        }, {
+            "title": "Load data with a different CRS",
+            "desc": "Load data with a different CRS than EPGS:4326",
+            "file": "load_data_different_crs",
+            "path": "data_management"
         }, {
             "title": "Upload to CARTO",
             "desc": "Upload data to CARTO",