feat: Add JSON I/O functionality for surface points

- Add JSON I/O module with schema definitions

- Implement surface points loading functionality

- Add comprehensive test suite for surface points I/O

- Create tutorial demonstrating JSON I/O usage

Author: flohorovicic

examples/tutorials/z_other_tutorials/json_io/01_surface_points_io.py

@@ -0,0 +1,95 @@
+"""
+Tutorial for JSON I/O operations in GemPy - Surface Points
+=======================================================
+
+This tutorial demonstrates how to save and load surface points data using JSON files in GemPy.
+"""
+
+import json
+import numpy as np
+import gempy as gp
+from gempy.modules.json_io import JsonIO
+
+# Create a sample surface points dataset
+# ------------------------------------
+
+# Create some sample surface points
+x = np.array([0, 1, 2, 3, 4])
+y = np.array([0, 1, 2, 3, 4])
+z = np.array([0, 1, 2, 3, 4])
+ids = np.array([0, 0, 1, 1, 2])  # Three different surfaces
+nugget = np.array([0.00002, 0.00002, 0.00002, 0.00002, 0.00002])
+
+# Create name to id mapping
+name_id_map = {f"surface_{id}": id for id in np.unique(ids)}
+
+# Create a SurfacePointsTable
+surface_points = gp.data.SurfacePointsTable.from_arrays(
+    x=x,
+    y=y,
+    z=z,
+    names=[f"surface_{id}" for id in ids],
+    nugget=nugget,
+    name_id_map=name_id_map
+)
+
+# Create a JSON file with the surface points data
+# ---------------------------------------------
+
+# Create the JSON structure
+json_data = {
+    "metadata": {
+        "name": "sample_model",
+        "creation_date": "2024-03-19",
+        "last_modification_date": "2024-03-19",
+        "owner": "tutorial"
+    },
+    "surface_points": [
+        {
+            "x": float(x[i]),
+            "y": float(y[i]),
+            "z": float(z[i]),
+            "id": int(ids[i]),
+            "nugget": float(nugget[i])
+        }
+        for i in range(len(x))
+    ],
+    "orientations": [],
+    "faults": [],
+    "series": [],
+    "grid_settings": {
+        "regular_grid_resolution": [10, 10, 10],
+        "regular_grid_extent": [0, 4, 0, 4, 0, 4],
+        "octree_levels": None
+    },
+    "interpolation_options": {}
+}
+
+# Save the JSON file
+with open("sample_surface_points.json", "w") as f:
+    json.dump(json_data, f, indent=4)
+
+# Load the surface points from JSON
+# -------------------------------
+
+# Load the model from JSON
+loaded_surface_points = JsonIO._load_surface_points(json_data["surface_points"])
+
+# Verify the loaded data
+print("\nOriginal surface points:")
+print(surface_points)
+print("\nLoaded surface points:")
+print(loaded_surface_points)
+
+# Verify the data matches
+print("\nVerifying data matches:")
+print(f"X coordinates match: {np.allclose(surface_points.xyz[:, 0], loaded_surface_points.xyz[:, 0])}")
+print(f"Y coordinates match: {np.allclose(surface_points.xyz[:, 1], loaded_surface_points.xyz[:, 1])}")
+print(f"Z coordinates match: {np.allclose(surface_points.xyz[:, 2], loaded_surface_points.xyz[:, 2])}")
+print(f"IDs match: {np.array_equal(surface_points.ids, loaded_surface_points.ids)}")
+print(f"Nugget values match: {np.allclose(surface_points.nugget, loaded_surface_points.nugget)}")
+
+# Print the name_id_maps to compare
+print("\nName to ID mappings:")
+print(f"Original: {surface_points.name_id_map}")
+print(f"Loaded: {loaded_surface_points.name_id_map}") 

examples/tutorials/z_other_tutorials/json_io/sample_surface_points.json

@@ -0,0 +1,65 @@
+{
+    "metadata": {
+        "name": "sample_model",
+        "creation_date": "2024-03-19",
+        "last_modification_date": "2024-03-19",
+        "owner": "tutorial"
+    },
+    "surface_points": [
+        {
+            "x": 0.0,
+            "y": 0.0,
+            "z": 0.0,
+            "id": 0,
+            "nugget": 2e-05
+        },
+        {
+            "x": 1.0,
+            "y": 1.0,
+            "z": 1.0,
+            "id": 0,
+            "nugget": 2e-05
+        },
+        {
+            "x": 2.0,
+            "y": 2.0,
+            "z": 2.0,
+            "id": 1,
+            "nugget": 2e-05
+        },
+        {
+            "x": 3.0,
+            "y": 3.0,
+            "z": 3.0,
+            "id": 1,
+            "nugget": 2e-05
+        },
+        {
+            "x": 4.0,
+            "y": 4.0,
+            "z": 4.0,
+            "id": 2,
+            "nugget": 2e-05
+        }
+    ],
+    "orientations": [],
+    "faults": [],
+    "series": [],
+    "grid_settings": {
+        "regular_grid_resolution": [
+            10,
+            10,
+            10
+        ],
+        "regular_grid_extent": [
+            0,
+            4,
+            0,
+            4,
+            0,
+            4
+        ],
+        "octree_levels": null
+    },
+    "interpolation_options": {}
+}

gempy/modules/json_io/__init__.py

@@ -0,0 +1,8 @@
+"""
+JSON I/O module for GemPy.
+This module provides functionality to load and save GemPy models to/from JSON files.
+"""
+
+from .json_operations import JsonIO
+
+__all__ = ['JsonIO'] 

gempy/modules/json_io/json_operations.py

@@ -0,0 +1,135 @@
+"""
+Module for JSON I/O operations in GemPy.
+This module provides functionality to load and save GemPy models to/from JSON files.
+"""
+
+import json
+from typing import Dict, Any, Optional, List
+import numpy as np
+
+from gempy.core.data.surface_points import SurfacePointsTable
+from gempy.core.data.orientations import OrientationsTable
+from gempy.core.data.structural_frame import StructuralFrame
+from gempy.core.data.grid import Grid
+from gempy.core.data.geo_model import GeoModel
+from .schema import SurfacePoint, GemPyModelJson
+
+
+class JsonIO:
+    """Class for handling JSON I/O operations for GemPy models."""
+    
+    @staticmethod
+    def load_model_from_json(file_path: str) -> GeoModel:
+        """
+        Load a GemPy model from a JSON file.
+        
+        Args:
+            file_path (str): Path to the JSON file
+            
+        Returns:
+            GeoModel: A new GemPy model instance
+        """
+        with open(file_path, 'r') as f:
+            data = json.load(f)
+            
+        # Validate the JSON data against our schema
+        if not JsonIO._validate_json_schema(data):
+            raise ValueError("Invalid JSON schema")
+            
+        # Load surface points
+        surface_points = JsonIO._load_surface_points(data['surface_points'])
+        
+        # TODO: Load other components
+        raise NotImplementedError("Only surface points loading is implemented")
+    
+    @staticmethod
+    def _load_surface_points(surface_points_data: List[SurfacePoint]) -> SurfacePointsTable:
+        """
+        Load surface points from JSON data.
+        
+        Args:
+            surface_points_data (List[SurfacePoint]): List of surface point dictionaries
+            
+        Returns:
+            SurfacePointsTable: A new SurfacePointsTable instance
+            
+        Raises:
+            ValueError: If the data is invalid or missing required fields
+        """
+        # Validate data structure
+        required_fields = {'x', 'y', 'z', 'id', 'nugget'}
+        for i, sp in enumerate(surface_points_data):
+            missing_fields = required_fields - set(sp.keys())
+            if missing_fields:
+                raise ValueError(f"Missing required fields in surface point {i}: {missing_fields}")
+            
+            # Validate data types
+            if not all(isinstance(sp[field], (int, float)) for field in ['x', 'y', 'z', 'nugget']):
+                raise ValueError(f"Invalid data type in surface point {i}. All coordinates and nugget must be numeric.")
+            if not isinstance(sp['id'], int):
+                raise ValueError(f"Invalid data type in surface point {i}. ID must be an integer.")
+        
+        # Extract coordinates and other data
+        x = np.array([sp['x'] for sp in surface_points_data])
+        y = np.array([sp['y'] for sp in surface_points_data])
+        z = np.array([sp['z'] for sp in surface_points_data])
+        ids = np.array([sp['id'] for sp in surface_points_data])
+        nugget = np.array([sp['nugget'] for sp in surface_points_data])
+        
+        # Create name_id_map from unique IDs
+        unique_ids = np.unique(ids)
+        name_id_map = {f"surface_{id}": id for id in unique_ids}
+        
+        # Create SurfacePointsTable
+        return SurfacePointsTable.from_arrays(
+            x=x,
+            y=y,
+            z=z,
+            names=[f"surface_{id}" for id in ids],
+            nugget=nugget,
+            name_id_map=name_id_map
+        )
+    
+    @staticmethod
+    def save_model_to_json(model: GeoModel, file_path: str) -> None:
+        """
+        Save a GemPy model to a JSON file.
+        
+        Args:
+            model (GeoModel): The GemPy model to save
+            file_path (str): Path where to save the JSON file
+        """
+        # TODO: Implement saving logic
+        raise NotImplementedError("JSON saving not yet implemented")
+    
+    @staticmethod
+    def _validate_json_schema(data: Dict[str, Any]) -> bool:
+        """
+        Validate the JSON data against the expected schema.
+        
+        Args:
+            data (Dict[str, Any]): The JSON data to validate
+            
+        Returns:
+            bool: True if valid, False otherwise
+        """
+        # Check required top-level keys
+        required_keys = {'metadata', 'surface_points', 'orientations', 'faults', 
+                        'series', 'grid_settings', 'interpolation_options'}
+        if not all(key in data for key in required_keys):
+            return False
+            
+        # Validate surface points
+        if not isinstance(data['surface_points'], list):
+            return False
+            
+        for sp in data['surface_points']:
+            required_sp_keys = {'x', 'y', 'z', 'id', 'nugget'}
+            if not all(key in sp for key in required_sp_keys):
+                return False
+            if not all(isinstance(sp[key], (int, float)) for key in ['x', 'y', 'z', 'nugget']):
+                return False
+            if not isinstance(sp['id'], int):
+                return False
+                
+        return True 

gempy/modules/json_io/schema.py

@@ -0,0 +1,55 @@
+"""
+Schema definitions for JSON I/O operations in GemPy.
+This module defines the expected structure of JSON files for loading and saving GemPy models.
+"""
+
+from typing import TypedDict, List, Dict, Any, Optional
+
+class SurfacePoint(TypedDict):
+    x: float
+    y: float
+    z: float
+    id: int
+    nugget: float
+
+class Orientation(TypedDict):
+    x: float
+    y: float
+    z: float
+    G_x: float
+    G_y: float
+    G_z: float
+    id: int
+    polarity: int
+
+class Fault(TypedDict):
+    name: str
+    id: int
+    is_active: bool
+
+class Series(TypedDict):
+    name: str
+    id: int
+    is_active: bool
+    is_fault: bool
+    order_series: int
+
+class GridSettings(TypedDict):
+    regular_grid_resolution: List[int]
+    regular_grid_extent: List[float]
+    octree_levels: Optional[int]
+
+class ModelMetadata(TypedDict):
+    name: str
+    creation_date: str
+    last_modification_date: str
+    owner: str
+
+class GemPyModelJson(TypedDict):
+    metadata: ModelMetadata
+    surface_points: List[SurfacePoint]
+    orientations: List[Orientation]
+    faults: List[Fault]
+    series: List[Series]
+    grid_settings: GridSettings
+    interpolation_options: Dict[str, Any]