> ## 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.

# Out-db rasters

> Raster values whose pixels stay in a file outside the DataFrame and are read when requested.

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

## OutDbSedonaRasterBase

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

Base class of out-db rasters, whose pixels stay in a file outside the DataFrame.

An out-db raster value references a source file, such as a GeoTIFF on S3, and
the bands to read from it. `as_numpy` and `as_rasterio` read the
pixels from that file when called, so the Python process needs access to it.
For S3 paths, Sedona builds the credentials from the Spark session's
`spark.hadoop.fs.s3a.*` configuration; see
`sedona.spark.raster.gdal_conf`.

Like the JVM reader, the pixel values have the source's scale and offset
applied, unless the `raster.reader.auto-rescale` reader parameter (or the
session's `spark.hadoop.raster.reader.auto-rescale`) turns rescaling off.
`with_bands` is not supported; convert the raster with `RS_AsInDb` in SQL
first.

#### 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"}
OutDbSedonaRasterBase.affine_trans: AffineTransform
```

Geo transform of the raster

### bands\_meta

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

Metadata of bands, including nodata value for each band

### crs\_wkt

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

CRS of the raster as a WKT string

### height

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

Height of the raster in pixel

### outdb\_meta

```python theme={"system"}
OutDbSedonaRasterBase.outdb_meta: OutDbMeta
```

Where the pixels of this raster are stored: the source path, the band
indices, the data type and the reader parameters.

### path

```python theme={"system"}
OutDbSedonaRasterBase.path: str
```

Path of the source file of this raster.

### width

```python theme={"system"}
OutDbSedonaRasterBase.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.

### set\_path()

```python theme={"system"}
set_path(path: str)
```

Point this raster at another copy of its source file.

Call it before reading the pixels: once this raster has opened its
source, it keeps reading from it.

#### Parameters

<ParamField path="path" type="str" required>
  The new source path, for example a local copy of the file.
</ParamField>

### with\_bands()

```python theme={"system"}
with_bands(new_data, nodata=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="float or sequence of 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>

## OutDbSedonaRaster

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

An out-db raster whose size, georeferencing and band metadata are known.

The raster can cover part of the source file, such as a tile, or a subset of
its bands. In that case `as_rasterio` returns a dataset backed by an
in-memory VRT that reads that region and those bands from the source.

#### 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>

<ParamField path="outdb_meta" type="OutDbMeta" required>
  Where the pixels of this raster are stored.
</ParamField>

### affine\_trans

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

Geo transform of the raster

### bands\_meta

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

Metadata of bands, including nodata value for each band

### crs\_wkt

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

CRS of the raster as a WKT string

### height

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

Height of the raster in pixel

### outdb\_meta

```python theme={"system"}
OutDbSedonaRaster.outdb_meta: OutDbMeta
```

Where the pixels of this raster are stored: the source path, the band
indices, the data type and the reader parameters.

### path

```python theme={"system"}
OutDbSedonaRaster.path: str
```

Path of the source file of this raster.

### width

```python theme={"system"}
OutDbSedonaRaster.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.

### generate\_vrt\_xml()

```python theme={"system"}
OutDbSedonaRaster.generate_vrt_xml(
    src_path,
    data_type,
    width,
    height,
    geo_transform,
    crs_wkt,
    off_x,
    off_y,
    band_indices,
    band_no_data,
    band_rescale: Optional[List[BandRescale]] = None,
) -> bytes
```

Assemble a VRT reading `band_indices` of a region of `src_path`.

With `band_rescale`, each band reads `value * scale + offset` through a
ComplexSource. Stored nodata is matched exactly before rescaling and becomes
NaN, as on the JVM. Nonzero finite nodata needs GDAL's native replace\_nodata
pixel function (GDAL >= 3.5). The padding outside the source reads the
NoDataValue too, or 0 for a band without one.

#### Parameters

<ParamField path="src_path" type="str" required>
  Path of the source dataset, in GDAL form (for example `/vsis3/...`).
</ParamField>

<ParamField path="data_type" type="str" required>
  GDAL data type of the VRT bands, such as `"Float64"`.
</ParamField>

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

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

<ParamField path="geo_transform" type="str" required>
  GDAL geotransform of the VRT, as six comma-separated numbers.
</ParamField>

<ParamField path="crs_wkt" type="str" required>
  CRS of the VRT as a WKT string, or None or empty for none.
</ParamField>

<ParamField path="off_x" type="int" required>
  Column of the source where the region starts.
</ParamField>

<ParamField path="off_y" type="int" required>
  Row of the source where the region starts.
</ParamField>

<ParamField path="band_indices" type="list of int" required>
  Zero-based indices of the source bands to read.
</ParamField>

<ParamField path="band_no_data" type="list of float" required>
  Stored NODATA value of each band, or None for a band without one.
</ParamField>

<ParamField path="band_rescale" type="Optional[List[BandRescale]]" default="None">
  (scale, offset) of each band, applied while reading.
</ParamField>

#### Returns

<ResponseField name="return" type="bytes">
  The VRT XML document.
</ResponseField>

### is\_vrt\_needed()

```python theme={"system"}
is_vrt_needed(ds: DatasetReader) -> bool
```

Whether reading this raster from the source dataset `ds` needs a VRT.

A VRT is needed when this raster covers only part of the source, or a
different set of its bands.

#### Parameters

<ParamField path="ds" type="DatasetReader" required>
  The opened source dataset.
</ParamField>

#### Returns

<ResponseField name="return" type="bool" />

### set\_path()

```python theme={"system"}
set_path(path: str)
```

Point this raster at another copy of its source file.

Call it before reading the pixels: once this raster has opened its
source, it keeps reading from it.

#### Parameters

<ParamField path="path" type="str" required>
  The new source path, for example a local copy of the file.
</ParamField>

### with\_bands()

```python theme={"system"}
with_bands(new_data, nodata=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="float or sequence of 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>

## LazyLoadOutDbSedonaRaster

```python theme={"system"}
LazyLoadOutDbSedonaRaster(path: str, params: Optional[Dict[str, str]])
```

An out-db raster that references a whole source file not opened yet.

Sedona returns this for a raster value that holds only a source path and
reader parameters. The first access to its size, georeferencing, band
metadata or pixels opens the file and reads its metadata.

#### Parameters

<ParamField path="path" type="str" required>
  Path of the source file.
</ParamField>

<ParamField path="params" type="Optional[Dict[str, str]]" required>
  Reader parameters of the raster, such as
  `raster.reader.auto-rescale`.
</ParamField>

### affine\_trans

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

Geo transform of the raster

### bands\_meta

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

Metadata of bands, including nodata value for each band

### crs\_wkt

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

CRS of the raster as a WKT string

### height

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

Height of the raster in pixel

### outdb\_meta

```python theme={"system"}
LazyLoadOutDbSedonaRaster.outdb_meta: OutDbMeta
```

Where the pixels of this raster are stored: the source path, the band
indices, the data type and the reader parameters.

### path

```python theme={"system"}
LazyLoadOutDbSedonaRaster.path: str
```

Path of the source file of this raster.

### width

```python theme={"system"}
LazyLoadOutDbSedonaRaster.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.

### set\_path()

```python theme={"system"}
set_path(path: str)
```

Point this raster at another copy of its source file.

#### Parameters

<ParamField path="path" type="str" required>
  The new source path, for example a local copy of the file.
</ParamField>

#### Raises

* `RuntimeError`: If this raster has already opened its source.

### with\_bands()

```python theme={"system"}
with_bands(new_data, nodata=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="float or sequence of 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>

## OutDbMeta

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

```python theme={"system"}
OutDbMeta(data_type, band_indices, path, params)
```

Metadata of out-db raster.

#### Parameters

<ParamField path="data_type" type="int" required>
  Data type of the pixels, as a `DataBuffer` type code.
</ParamField>

<ParamField path="band_indices" type="list of int" required>
  Zero-based indices of the bands of the source file that this raster reads.
</ParamField>

<ParamField path="path" type="str" required>
  Path of the source file.
</ParamField>

<ParamField path="params" type="dict of str to str" required>
  Reader parameters of the raster, such as
  `raster.reader.auto-rescale`.
</ParamField>


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