# This file is automatically generated by ravepipeline::mcptool_build(). 
# Please never edit this file by hand!
name: ieegio-mcp_tool_volume_to_surface
description: Convert a previously cached volume (identified by its digest ID) to a
  surface mesh using isosurface extraction. The volume is retrieved from the volume
  cache, converted to a surface using volume_to_surface, and stored in the surface
  cache. Returns the new surface ID and metadata. This tool bridges volume and surface
  operations, enabling workflows that start with volumetric data and produce surface
  meshes for visualization or analysis. Before using this tool, you must first read
  and cache the volume using ieegio-mcp_tool_volume_read, which returns the volume
  ID needed for this conversion. The resulting surface can be accessed with surface
  tools like ieegio-mcp_tool_surface_info, and can be exported via ieegio-mcp_tool_surface_write.
parameters:
  type: object
  properties:
    threshold_ub:
      type: number
      description: 'Upper threshold for isosurface extraction. Voxels below this value
        are included. Use NA for no upper limit (default). Example values: NA, 1000,
        255'
      default: .na.real
      examples:
      - NA
      - '1000'
      - '255'
    threshold_lb:
      type: number
      description: 'Lower threshold for isosurface extraction. Voxels above this value
        are included in the surface. Defaults to 0.5 for binary or probablistic masks
        Example values: 0.5, 100, 0'
      default: 0.5
      examples:
      - '0.5'
      - '100'
      - '0'
    degree:
      type: integer
      description: 'Degree of smoothing (passed to vcg_smooth_implicit). Defaults
        to 2. Example values: 2, 3'
      default: 2.0
      examples:
      - '2'
      - '3'
    lambda:
      type: number
      description: 'Smoothing parameter for surface mesh. Higher values produce smoother
        surfaces. Set to negative or NA to disable smoothing. Defaults to 0.2. Example
        values: 0.2, 0.5, -1'
      default: 0.2
      examples:
      - '0.2'
      - '0.5'
      - '-1'
    id:
      type: string
      description: 'The digest-based identifier of the cached volume. This ID is returned
        by ieegio-mcp_tool_volume_read. Example values: "a3f5e8d9c1b2", "f7e4b2a1c6d8"'
      examples:
      - a3f5e8d9c1b2
      - f7e4b2a1c6d8
  required:
  - id
category: execution
returns:
  type: object
  properties:
    error:
      type: string
      description: Character, error message if success is FALSE
    n_faces:
      type: integer
      description: Integer, number of faces in the generated surface
    n_vertices:
      type: integer
      description: Integer, number of vertices in the generated surface
    surface_id:
      type: string
      description: Character, unique digest-based identifier for the new surface
    volume_id:
      type: string
      description: Character, the volume identifier that was converted
    success:
      type: boolean
      description: Logical, whether the conversion completed successfully
implementation_example: |
  # Convert a volume to surface
  # Note: .state_env is automatically provided when called via MCP.
  # AI does not need to specify this argument. The examples only use
  # .state_env to make the code runnable for demonstration purposes.
  sample_file <- ieegio_sample_data("nifti/rnifti_example.nii.gz")
  state_env <- fastmap::fastmap()
  read_result <- ieegio:::mcp_tool_volume_read(sample_file, .state_env = state_env)
  # Convert to surface with default smoothing
  ieegio:::mcp_tool_volume_to_surface(
    id = read_result$id,
    threshold_lb = 20,
    .state_env = state_env
  )
  #
  #> $success
  #> [1] TRUE
  #> 
  #> $volume_id
  #> [1] "e1ccd803b62bb9390d3debbd05f32042"
  #> 
  #> $surface_id
  #> [1] "175bb346f688b9cf7dc2fd3ce0db3d43"
  #> 
  #> $n_vertices
  #> [1] 21580
  #> 
  #> $n_faces
  #> [1] 43568
  #>
execution_time: 1.357
