# This file is automatically generated by ravepipeline::mcptool_build(). 
# Please never edit this file by hand!
name: ieegio-mcp_tool_volume_read
description: 'Read a neuroimaging volume file (NIfTI or MGZ format) and cache it in
  memory with a unique digest-based ID. Internally the tool calls function `ieegio::as_ieegio_volume`.
  The volume is stored in session state for efficient reuse by other MCP tools. All
  volumes are normalized to NIfTI format internally. Returns volume metadata and the
  ID to reference this volume in subsequent operations. Use the returned ID with other
  tools: ieegio-mcp_tool_volume_write to save the volume to a file, ieegio-mcp_tool_volume_info
  to get detailed header information, ieegio-mcp_tool_volume_list to see all cached
  volumes, or ieegio-mcp_tool_volume_clear to remove volumes from cache.'
parameters:
  type: object
  properties:
    file_path:
      type: string
      description: 'Absolute or relative path to the volume file. Supported formats:
        .nii, .nii.gz, .mgz. Example values: "/path/to/brain.nii.gz", "data/subject01.mgz"'
      examples:
      - /path/to/brain.nii.gz
      - data/subject01.mgz
  required:
  - file_path
category: info
returns:
  type: object
  properties:
    error:
      type: string
      description: Character, error message if success is FALSE
    vox2ras:
      type: number
      description: Numeric matrix, 4x4 voxel-to-RAS transformation matrix
    format:
      type: string
      description: Character, original file format ("nifti" or "mgz")
    type:
      type: array
      description: Character vector, volume type information
      items:
        type: string
    shape:
      type: array
      description: Integer vector, volume dimensions (width, height, depth, ...)
      items:
        type: integer
    file_path:
      type: string
      description: Character, the original file path that was read
    id:
      type: string
      description: Character, unique digest-based identifier for this volume
    success:
      type: boolean
      description: Logical, whether the volume was successfully read and cached
implementation_example: |
  # Read a NIfTI volume file
  # Note: .state_env is automatically provided when called via MCP.
  # The example includes it only to make the code runnable for documentation.
  sample_file <- ieegio_sample_data("nifti/rnifti_example.nii.gz")
  ieegio:::mcp_tool_volume_read(sample_file)
  #
  #> $success
  #> [1] TRUE
  #> 
  #> $id
  #> [1] "e1ccd803b62bb9390d3debbd05f32042"
  #> 
  #> $file_path
  #> [1] "/Users/dipterix/Library/Caches/org.R-project.R/R/ieegio/sample_data/nifti/rnifti_example.nii.gz"
  #> 
  #> $shape
  #> [1] 96 96 60
  #> 
  #> $type
  #> [1] "rnifti" "nifti" 
  #> 
  #>  [ reached 'max' / getOption("max.print") -- omitted 2 entries ]
execution_time: 0.022
