> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Raster objects

> The Python objects that hold raster values, with their pixels as NumPy arrays or rasterio datasets.

```python theme={"system"}
from sedona.spark.raster import SedonaRaster
```

## SedonaRaster

```python theme={"system"}
SedonaRaster(
    width: int,
    height: int,
    bands_meta: List[SampleDimension],
    affine_trans: AffineTransform,
    crs_wkt: str,
)
```

A raster value from a Sedona raster column.

`DataFrame.collect()` and Python UDFs receive raster column values as
`SedonaRaster` objects. Read the pixels with `as_numpy` or
`as_rasterio`, and the georeferencing with `affine_trans` and
`crs_wkt`. Call `close`, or use the raster as a context manager,
to release the resources it holds.

Sedona creates these objects when it reads a raster value; you do not
construct them yourself.

#### Parameters

<ParamField path="width" type="int" required>
  Width of the raster in pixels.
</ParamField>

<ParamField path="height" type="int" required>
  Height of the raster in pixels.
</ParamField>

<ParamField path="bands_meta" type="List[SampleDimension]" required>
  Metadata of each band.
</ParamField>

<ParamField path="affine_trans" type="AffineTransform" required>
  Transform from pixel coordinates to world coordinates.
</ParamField>

<ParamField path="crs_wkt" type="str" required>
  CRS of the raster as a WKT string.
</ParamField>

### affine\_trans

```python theme={"system"}
SedonaRaster.affine_trans: AffineTransform
```

Geo transform of the raster

### bands\_meta

```python theme={"system"}
SedonaRaster.bands_meta: List[SampleDimension]
```

Metadata of bands, including nodata value for each band

### crs\_wkt

```python theme={"system"}
SedonaRaster.crs_wkt: str
```

CRS of the raster as a WKT string

### height

```python theme={"system"}
SedonaRaster.height: int
```

Height of the raster in pixel

### width

```python theme={"system"}
SedonaRaster.width: int
```

Width of the raster in pixel

### as\_numpy()

```python theme={"system"}
as_numpy() -> np.ndarray
```

Get the bands data as an numpy array in CHW layout

### as\_numpy\_masked()

```python theme={"system"}
as_numpy_masked() -> np.ndarray
```

Get the bands data as an numpy array in CHW layout, with nodata
values masked as nan.

### as\_rasterio()

```python theme={"system"}
as_rasterio() -> DatasetReader
```

Retrieve the raster as an rasterio DatasetReader

### close()

```python theme={"system"}
close()
```

Release all resources allocated for this sedona raster. The rasterio
DatasetReader returned by as\_rasterio() will also be closed.

### with\_bands()

```python theme={"system"}
with_bands(
    new_data: np.ndarray,
    nodata: Optional[Union[float, Sequence[float]]] = None,
) -> SedonaRaster
```

Replace pixel data, preserving spatial metadata.

Only supported on in-db rasters (`InDbSedonaRaster`); other rasters
raise `TypeError`.

#### Parameters

<ParamField path="new_data" type="np.ndarray" required>
  New pixel data, of shape (height, width) for a single band or
  (bands, height, width). Height and width must match this raster;
  the band count and dtype may differ.
</ParamField>

<ParamField path="nodata" type="Optional[Union[float, Sequence[float]]]" default="None">
  NODATA value of the output bands: a scalar for every band, or one
  value per band. Use `float('nan')` for a band without NODATA. When
  omitted, the output bands inherit NODATA from the source bands.
</ParamField>

#### Returns

<ResponseField name="return" type="SedonaRaster">
  A new raster with the given pixel data and the same spatial metadata.
</ResponseField>

## AffineTransform

Import from `sedona.spark.raster.meta`.

```python theme={"system"}
AffineTransform(scale_x, skew_y, skew_x, scale_y, ip_x, ip_y, pixel_anchor: PixelAnchor)
```

Affine transform from pixel coordinates to world coordinates.

The pixel at column `col` and row `row` maps to
`x = ip_x + col * scale_x + row * skew_x` and
`y = ip_y + col * skew_y + row * scale_y`. `repr()` shows the transform
as a 3x3 matrix.

#### Parameters

<ParamField path="scale_x" type="float" required>
  Pixel width in world units.
</ParamField>

<ParamField path="skew_y" type="float" required>
  Change in y per column; 0 for a raster without rotation.
</ParamField>

<ParamField path="skew_x" type="float" required>
  Change in x per row; 0 for a raster without rotation.
</ParamField>

<ParamField path="scale_y" type="float" required>
  Pixel height in world units, negative for a north-up raster.
</ParamField>

<ParamField path="ip_x" type="float" required>
  X coordinate of the upper-left pixel.
</ParamField>

<ParamField path="ip_y" type="float" required>
  Y coordinate of the upper-left pixel.
</ParamField>

<ParamField path="pixel_anchor" type="PixelAnchor" required>
  Whether `ip_x` and `ip_y` refer to the center or the upper-left
  corner of that pixel.
</ParamField>

### translate()

```python theme={"system"}
translate(offset_x: float, offset_y: float)
```

Return the transform of a raster whose origin is offset by whole pixels.

#### Parameters

<ParamField path="offset_x" type="float" required>
  Offset in pixel columns.
</ParamField>

<ParamField path="offset_y" type="float" required>
  Offset in pixel rows.
</ParamField>

#### Returns

<ResponseField name="return" type="AffineTransform">
  A new transform whose origin is pixel (`offset_x`, `offset_y`)
  of this one, for example the transform of a tile cut from the raster.
</ResponseField>

### with\_anchor()

```python theme={"system"}
with_anchor(pixel_anchor: PixelAnchor)
```

Return the same transform expressed for another pixel anchor.

#### Parameters

<ParamField path="pixel_anchor" type="PixelAnchor" required>
  The pixel anchor of the returned transform.
</ParamField>

#### Returns

<ResponseField name="return" type="AffineTransform">
  This transform if it already uses `pixel_anchor`; otherwise a new
  transform whose origin is shifted by half a pixel.
</ResponseField>

## PixelAnchor

Import from `sedona.spark.raster.meta`.

Anchor of the pixel cell. GeoTools anchors the coordinates at the center
of pixels, while GDAL anchors the coordinates at the upper-left corner of
the pixels. This difference requires us to convert the affine
transformation between these conventions.

#### Values

<ResponseField name="CENTER" type="PixelAnchor">
  `1`
</ResponseField>

<ResponseField name="UPPER_LEFT" type="PixelAnchor">
  `2`
</ResponseField>

## SampleDimension

Import from `sedona.spark.raster.meta`.

```python theme={"system"}
SampleDimension(description, offset, scale, nodata)
```

Raster band metadata.

#### Parameters

<ParamField path="description" type="str" required>
  Description of the band.
</ParamField>

<ParamField path="offset" type="float" required>
  Offset of the band: a stored pixel value means `value * scale + offset`.
</ParamField>

<ParamField path="scale" type="float" required>
  Scale of the band.
</ParamField>

<ParamField path="nodata" type="float" required>
  NODATA value of the band, or NaN if the band has none.
</ParamField>

## SedonaUtils

Import from `sedona.spark.raster_utils.SedonaUtils`.

```python theme={"system"}
SedonaUtils()
```

Notebook display helpers for Sedona DataFrames.

### display\_image()

```python theme={"system"}
SedonaUtils.display_image(df)
```

Display raster images in a Jupyter notebook.

Accepts DataFrames with either:

* A raster column (GridCoverage2D) — auto-applies RS\_AsImage
* An HTML image column from RS\_AsImage() — renders directly

Falls back to the SedonaMapUtils HTML table path for other DataFrames.

#### Parameters

<ParamField path="df" type="pyspark.sql.DataFrame" required>
  The DataFrame to display. All of its rows are collected to the
  driver, so limit large DataFrames first.
</ParamField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.