Updating the documentation to include the new methods

Author: yasseraleman

docs/source/modules/freesurfertools.rst

@@ -16,6 +16,8 @@ Key Features
 - Surface-based morphometry computation
 - Container technology integration
 - Multi-format conversion capabilities
+- Extract CRAS coordinates from transform files
+- Parse FreeSurfer LTA transform files
 
 Main Classes
 ------------
@@ -29,6 +31,7 @@ Key Methods:
 - ``correct_parcellation()``: Fix unlabeled vertices in parcellations  
 - ``save_as_gcs()``: Convert annotation to GCS format
 - ``get_region_info()``: Extract parcellation region information
+- ``get_cras()``: Extract CRAS coordinates from Talairach transform file
 
 Common Usage Examples
 ---------------------
@@ -58,4 +61,25 @@ Surface morphometry processing::
     morphometry_table = fs.compute_morphometry_table(
         subjects_dir="/path/to/freesurfer/subjects",
         parcellation="aparc.a2009s"
+    )
+
+Transform and coordinate processing::
+
+    from clabtoolkit.freesurfertools import AnnotParcellation, parse_freesurfer_lta, get_cras_coordinates
+    
+    # Extract CRAS coordinates from an annotation object
+    annot = AnnotParcellation("lh.aparc.a2009s.annot")
+    cras_coords = annot.get_cras()
+    print(f"CRAS coordinates: {cras_coords}")
+    
+    # Parse LTA transform file
+    lta_data = parse_freesurfer_lta("/path/to/transforms/talairach.lta")
+    transform_matrix = lta_data['transform_matrix']
+    source_cras = lta_data['source_cras']
+    dest_cras = lta_data['dest_cras']
+    
+    # Extract CRAS coordinates directly from LTA file
+    cras_coordinates = get_cras_coordinates(
+        "/path/to/transforms/talairach.lta", 
+        source=True
     )

docs/source/modules/imagetools.rst

@@ -16,6 +16,7 @@ Key Features
 - Quality control and preprocessing utilities
 - Multi-modal image processing support
 - Structuring element generation for morphological operations
+- 3D/4D scalar data interpolation at specified coordinates
 
 Main Classes
 ------------
@@ -75,4 +76,39 @@ Image quality control::
     
     # Get image statistics
     stats = morph.get_image_statistics(binary_data)
-    print(f"Volume: {stats['volume']} voxels")
+    print(f"Volume: {stats['volume']} voxels")
+
+3D/4D data interpolation::
+
+    from clabtoolkit.imagetools import interpolate
+    import numpy as np
+    import nibabel as nib
+    
+    # Load 3D scalar volume
+    img = nib.load("/path/to/scalar_data.nii.gz")
+    scalar_data = img.get_fdata()
+    
+    # Define voxel coordinates for interpolation (Nx3 array)
+    vertices_vox = np.array([
+        [10.5, 20.3, 15.7],  # fractional coordinates allowed
+        [25.2, 30.1, 45.9],
+        [12.0, 18.5, 22.3]
+    ])
+    
+    # Interpolate values at specified coordinates
+    interpolated_values = interpolate(
+        scalar_data=scalar_data,
+        vertices_vox=vertices_vox,
+        interp_method="linear"  # options: 'linear', 'nearest', 'slinear'
+    )
+    
+    # For 4D data (e.g., time series)
+    functional_img = nib.load("/path/to/4d_functional.nii.gz")
+    functional_data = functional_img.get_fdata()  # shape: (x, y, z, time)
+    
+    # Interpolate 4D data - returns values for each timepoint
+    time_series_values = interpolate(
+        scalar_data=functional_data,
+        vertices_vox=vertices_vox,
+        interp_method="linear"
+    )  # shape: (n_vertices, n_timepoints)

docs/source/modules/surfacetools.rst

@@ -30,6 +30,7 @@ Key Methods:
 - ``load_parcellation()``: Load parcellation overlays
 - ``plot()``: Interactive 3D visualization with customization options
 - ``get_mesh_info()``: Extract surface geometry information
+- ``map_volume_to_surface()``: Project 3D/4D volumetric data onto surface mesh vertices
 
 Common Usage Examples
 ---------------------
@@ -68,4 +69,27 @@ Multi-view visualization::
         views=['lateral', 'medial', 'dorsal'],
         scalar_map=True,
         save_figure="/path/to/output.png"
+    )
+
+Volume-to-surface mapping::
+
+    # Project volumetric data onto surface
+    from pathlib import Path
+    
+    # Load surface
+    surface = Surface("/path/to/lh.pial")
+    
+    # Map 3D structural image to surface
+    surface_values = surface.map_volume_to_surface(
+        image="/path/to/structural.nii.gz",
+        method="nilearn",
+        interp_method="linear"
+    )
+    
+    # Map 4D functional data to surface
+    functional_values = surface.map_volume_to_surface(
+        image="/path/to/functional_4d.nii.gz",
+        method="custom",
+        interp_method="linear",
+        overlay_name="activation"
     )