### Install gsffile with pip

Source: https://github.com/angelo-peronio/gsffile/blob/master/README.md

Install the gsffile library using pip for Python package management.

```bash
python -m pip install gsffile
```

--------------------------------

### Complete Roundtrip Example

Source: https://context7.com/angelo-peronio/gsffile/llms.txt

Demonstrates the complete workflow of creating image data, writing it to a GSF file with metadata, and reading it back to verify data integrity.

```APIDOC
## Complete Roundtrip Example

### Description
This example demonstrates the complete workflow of creating synthetic AFM-like surface data, writing it to a GSF file with associated metadata using `write_gsf`, and then reading it back using `read_gsf` to verify data integrity.

### Request Example
```python
import numpy as np
from gsffile import read_gsf, write_gsf

# Create synthetic AFM-like surface data
x = np.linspace(0, 4 * np.pi, 256)
y = np.linspace(0, 4 * np.pi, 256)
X, Y = np.meshgrid(x, y)
surface_data = (np.sin(X) * np.cos(Y) * 100e-9).astype(np.float32)

# Metadata for a typical AFM scan
afm_metadata = {
    "XReal": 10e-6,              # 10 micrometer scan width
    "YReal": 10e-6,              # 10 micrometer scan height
    "XOffset": 50e-6,
    "YOffset": 50e-6,
    "XYUnits": "m",
    "ZUnits": "m",
    "Title": "AFM surface topography",
    "ScanRate": "1.0 Hz",
    "Instrument": "Custom AFM",
    "Date": "2024-01-15",
}

# Write the data
output_path = "afm_scan.gsf"
write_gsf(output_path, surface_data, afm_metadata)

# Read it back
loaded_data, loaded_metadata = read_gsf(output_path)

# Verification (optional)
print(f"Original data shape: {surface_data.shape}")
print(f"Loaded data shape: {loaded_data.shape}")
print(f"Data matches: {np.allclose(surface_data, loaded_data)}")
print(f"Metadata keys match: {set(afm_metadata.keys()) == set(loaded_metadata.keys())}")
```

### Response
This example does not produce a direct API response but demonstrates successful file writing and reading. The output includes print statements to verify data and metadata integrity.
```

--------------------------------

### Quickstart: Read and Write GSF Files

Source: https://github.com/angelo-peronio/gsffile/blob/master/README.md

Demonstrates basic usage of gsffile for writing a NumPy array to a .gsf file and then reading it back. Note that Gwyddion Simple Field format only supports 32-bit floating point data.

```python
>>> from gsffile import read_gsf, write_gsf
>>> import numpy as np

# The Gwyddion Simple Field format supports only 32-bit floating point data.
>>> data = np.eye(100, dtype=np.float32)

# Optional metadata.
>>> metadata = {
...    "XReal": 5e-05,
...    "YReal": 5e-05,
...    "XYUnits": "m",
...    "ZUnits": "V",
...    "CustomKey": 33,
...    }

>>> write_gsf("example.gsf", data, metadata)

>>> data, metadata = read_gsf("example.gsf")

```

--------------------------------

### Install gsffile with conda

Source: https://github.com/angelo-peronio/gsffile/blob/master/README.md

Install the gsffile library using conda, a package and environment manager.

```bash
conda install conda-forge::gsffile
```

--------------------------------

### Complete Roundtrip Example for GSF files

Source: https://context7.com/angelo-peronio/gsffile/llms.txt

Demonstrates creating synthetic AFM-like surface data, writing it to a GSF file with metadata, and then reading it back to verify data integrity.

```python
import numpy as np
from gsffile import read_gsf, write_gsf

# Create synthetic AFM-like surface data
x = np.linspace(0, 4 * np.pi, 256)
y = np.linspace(0, 4 * np.pi, 256)
X, Y = np.meshgrid(x, y)
surface_data = (np.sin(X) * np.cos(Y) * 100e-9).astype(np.float32)

# Metadata for a typical AFM scan
afm_metadata = {
    "XReal": 10e-6,              # 10 micrometer scan width
    "YReal": 10e-6,              # 10 micrometer scan height
    "XOffset": 50e-6,            # Scan position offset
    "YOffset": 50e-6,
    "XYUnits": "m",
    "ZUnits": "m",
    "Title": "AFM surface topography",
    "ScanRate": "1.0 Hz",
    "Instrument": "Custom AFM",
    "Date": "2024-01-15",
}

# Write the data
output_path = "afm_scan.gsf"
write_gsf(output_path, surface_data, afm_metadata)

# Read it back
loaded_data, loaded_metadata = read_gsf(output_path)
```

--------------------------------

### Install gsffile with pip or conda

Source: https://context7.com/angelo-peronio/gsffile/llms.txt

Install the gsffile library using either pip or conda to add Gwyddion Simple Field file support to your Python environment.

```bash
python -m pip install gsffile
```

```bash
conda install conda-forge::gsffile
```

--------------------------------

### View gsffile Documentation

Source: https://github.com/angelo-peronio/gsffile/blob/master/README.md

Access the detailed documentation for the gsffile module directly from the command line using Python's help function.

```bash
python -c "import gsffile; help(gsffile)"
```

--------------------------------

### Release Project Script

Source: https://github.com/angelo-peronio/gsffile/blob/master/development.md

Execute this PowerShell script to release a new version of the project. Use the -Bump parameter to specify the version increment (e.g., patch, minor, major).

```powershell
.\scripts\Release-Project.ps1 -Bump patch
```

--------------------------------

### Verify Roundtrip Integrity

Source: https://context7.com/angelo-peronio/gsffile/llms.txt

Asserts that loaded data matches the original surface data in shape and content, and confirms the data type is float32. Prints success message and metadata keys.

```python
assert loaded_data.shape == surface_data.shape
assert loaded_data.dtype == np.float32
np.testing.assert_array_equal(loaded_data, surface_data)
print(f"Roundtrip successful: {loaded_data.shape} array preserved")
print(f"Metadata fields: {list(loaded_metadata.keys())}")
```

--------------------------------

### write_gsf Function

Source: https://context7.com/angelo-peronio/gsffile/llms.txt

Write a NumPy array to a Gwyddion Simple Field file (.gsf). Supports 0-, 1-, and 2-dimensional float32 arrays, along with optional metadata.

```APIDOC
## write_gsf Function

### Description
Writes a NumPy array to a Gwyddion Simple Field file (.gsf). The function accepts 0-, 1-, and 2-dimensional float32 arrays (lower dimensional arrays are automatically reshaped to 2D), and optional metadata including physical dimensions, units, and custom key-value pairs. The GSF format supports special float values like Inf and NaN.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **filepath** (str) - Required - The path to the output .gsf file.
- **data** (np.ndarray) - Required - A 0-, 1-, or 2-dimensional NumPy array of type float32.
- **metadata** (dict) - Optional - A dictionary containing metadata for the GSF file. Supported keys include:
  - XReal (float): Physical width in XYUnits.
  - YReal (float): Physical height in XYUnits.
  - XOffset (float): X origin offset.
  - YOffset (float): Y origin offset.
  - XYUnits (str): Units for XReal, YReal.
  - ZUnits (str): Units for data values.
  - Title (str): Title of the data.
  - Any other custom key-value pairs.

### Request Example
```python
import numpy as np
from gsffile import write_gsf

# Create sample 2D image data (must be float32)
data = np.random.uniform(0, 1, size=(100, 200)).astype(np.float32)

# Define optional metadata with physical dimensions and units
metadata = {
    "XReal": 5e-05,      # Physical width in XYUnits (50 micrometers)
    "YReal": 2.5e-05,    # Physical height in XYUnits (25 micrometers)
    "XOffset": 0.0,
    "YOffset": 0.0,
    "XYUnits": "m",
    "ZUnits": "V",
    "Title": "Surface topography scan",
    "CustomField": "Any custom metadata value",
    "ScanSpeed": 1.5,
}

# Write to GSF file (extension must be .gsf)
write_gsf("output.gsf", data, metadata)

# Writing 1D data (automatically reshaped to 2D)
line_profile = np.linspace(0, 1, 256).astype(np.float32)
write_gsf("profile.gsf", line_profile)

# Writing data with special float values (Inf, NaN supported)
data_with_nan = np.array([[1.0, np.nan], [np.inf, -np.inf]], dtype=np.float32)
write_gsf("special_values.gsf", data_with_nan)
```

### Response
This function does not return any value upon successful execution. Errors are raised if the file cannot be written or if the input data is invalid.
```

--------------------------------

### Read GSF file into NumPy array and metadata

Source: https://context7.com/angelo-peronio/gsffile/llms.txt

Read image data and metadata from a .gsf file. Returns a tuple containing a 2D float32 NumPy array and a metadata dictionary. XRes and YRes are derived and not included in the metadata.

```python
from pathlib import Path
from gsffile import read_gsf

# Read GSF file - returns (data, metadata) tuple
data, metadata = read_gsf("output.gsf")

# Access array properties
print(f"Image shape: {data.shape}")        # e.g., (100, 200)
print(f"Data type: {data.dtype}")          # float32
print(f"Value range: {data.min():.3f} to {data.max():.3f}")

# Access standard metadata fields
if "XReal" in metadata:
    print(f"Physical width: {metadata['XReal']} {metadata.get('XYUnits', '')}")
if "YReal" in metadata:
    print(f"Physical height: {metadata['YReal']} {metadata.get('XYUnits', '')}")
if "ZUnits" in metadata:
    print(f"Z units: {metadata['ZUnits']}")
if "Title" in metadata:
    print(f"Title: {metadata['Title']}")

# Access custom metadata fields
for key, value in metadata.items():
    print(f"{key}: {value}")

# Using Path objects
data, metadata = read_gsf(Path("/path/to/scan.gsf"))

# Error handling
try:
    data, metadata = read_gsf("invalid_file.gsf")
except ValueError as e:
    print(f"Invalid GSF file: {e}")  # Magic line not found
except KeyError as e:
    print(f"Missing required metadata: {e}")  # XRes/YRes missing
```

--------------------------------

### Write GSF with Metadata

Source: https://context7.com/angelo-peronio/gsffile/llms.txt

Writes a NumPy array to a GSF file, including standard and custom metadata. Standard fields like XRes/YRes are auto-derived. Ensure data is a NumPy array with dtype float32.

```python
from gsffile import write_gsf
import numpy as np

# Standard GSF metadata fields (all optional except XRes/YRes which are auto-derived)
standard_metadata = {
    # Dimensions (automatically set from data.shape - DO NOT specify manually)
    # "XRes": int,        # Number of columns (auto from data.shape[1])
    # "YRes": int,        # Number of rows (auto from data.shape[0])

    # Physical dimensions
    "XReal": 1e-6,        # float: Physical width in XYUnits
    "YReal": 1e-6,        # float: Physical height in XYUnits

    # Origin offsets
    "XOffset": 0.0,       # float: X origin offset in XYUnits
    "YOffset": 0.0,       # float: Y origin offset in XYUnits

    # Units
    "XYUnits": "m",       # str: Unit for XReal, YReal, XOffset, YOffset
    "ZUnits": "m",        # str: Unit for data values

    # Description
    "Title": "Image title",  # str: Human-readable title
}

# Custom metadata can use any key-value pairs (converted to strings)
custom_metadata = standard_metadata | {
    "Operator": "John Doe",
    "Temperature": 293.15,
    "SampleID": "SAMPLE-001",
}

data = np.ones((64, 64), dtype=np.float32)
write_gsf("with_metadata.gsf", data, custom_metadata)
```

--------------------------------

### Write NumPy array to GSF file

Source: https://context7.com/angelo-peronio/gsffile/llms.txt

Write 0-, 1-, or 2-dimensional float32 NumPy arrays to a .gsf file. Supports optional metadata including physical dimensions, units, and custom key-value pairs. Special float values like Inf and NaN are supported.

```python
import numpy as np
from gsffile import write_gsf

# Create sample 2D image data (must be float32)
data = np.random.uniform(0, 1, size=(100, 200)).astype(np.float32)

# Define optional metadata with physical dimensions and units
metadata = {
    "XReal": 5e-05,      # Physical width in XYUnits (50 micrometers)
    "YReal": 2.5e-05,    # Physical height in XYUnits (25 micrometers)
    "XOffset": 0.0,      # X origin offset
    "YOffset": 0.0,      # Y origin offset
    "XYUnits": "m",      # Units for XReal, YReal (meters)
    "ZUnits": "V",       # Units for data values (Volts)
    "Title": "Surface topography scan",
    "CustomField": "Any custom metadata value",
    "ScanSpeed": 1.5,    # Custom numeric metadata
}

# Write to GSF file (extension must be .gsf)
write_gsf("output.gsf", data, metadata)

# Writing 1D data (automatically reshaped to 2D)
line_profile = np.linspace(0, 1, 256).astype(np.float32)
write_gsf("profile.gsf", line_profile)

# Writing data with special float values (Inf, NaN supported)
data_with_nan = np.array([[1.0, np.nan], [np.inf, -np.inf]], dtype=np.float32)
write_gsf("special_values.gsf", data_with_nan)
```

--------------------------------

### read_gsf Function

Source: https://context7.com/angelo-peronio/gsffile/llms.txt

Read image data and metadata from a Gwyddion Simple Field file (.gsf). Returns a tuple containing the 2D NumPy array of float32 data and a dictionary of metadata.

```APIDOC
## read_gsf Function

### Description
Reads image data and metadata from a Gwyddion Simple Field file (.gsf). Returns a tuple containing the 2D NumPy array of float32 data and a dictionary of metadata. The XRes and YRes fields are automatically derived from the array shape and not included in the metadata dictionary.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **filepath** (str or Path) - Required - The path to the .gsf file to read.

### Request Example
```python
from pathlib import Path
from gsffile import read_gsf

# Read GSF file - returns (data, metadata) tuple
data, metadata = read_gsf("output.gsf")

# Access array properties
print(f"Image shape: {data.shape}")
print(f"Data type: {data.dtype}")
print(f"Value range: {data.min():.3f} to {data.max():.3f}")

# Access standard metadata fields
if "XReal" in metadata:
    print(f"Physical width: {metadata['XReal']} {metadata.get('XYUnits', '')}")
if "YReal" in metadata:
    print(f"Physical height: {metadata['YReal']} {metadata.get('XYUnits', '')}")
if "ZUnits" in metadata:
    print(f"Z units: {metadata['ZUnits']}")
if "Title" in metadata:
    print(f"Title: {metadata['Title']}")

# Access custom metadata fields
for key, value in metadata.items():
    print(f"{key}: {value}")

# Using Path objects
data, metadata = read_gsf(Path("/path/to/scan.gsf"))

# Error handling
try:
    data, metadata = read_gsf("invalid_file.gsf")
except ValueError as e:
    print(f"Invalid GSF file: {e}")  # Magic line not found
except KeyError as e:
    print(f"Missing required metadata: {e}")  # XRes/YRes missing
```

### Response
#### Success Response (200)
- **data** (np.ndarray) - A 2D NumPy array of type float32 representing the image data.
- **metadata** (dict) - A dictionary containing the metadata read from the GSF file. Standard keys include XReal, YReal, XOffset, YOffset, XYUnits, ZUnits, Title. Custom fields are also included.

#### Response Example
```json
{
  "data": [[1.0, 2.0], [3.0, 4.0]],
  "metadata": {
    "XReal": 5e-05,
    "YReal": 2.5e-05,
    "XYUnits": "m",
    "ZUnits": "V",
    "Title": "Surface topography scan"
  }
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.