AR1/docs/import/raster.md

# Raster Data Import

Import raster data from files, URLs, or cloud storage.

## Overview

Raster data import supports multiple formats and import methods for grid-based spatial data.

## Supported Formats

### GeoTIFF

- **Extension**: `.tif`, `.tiff`, `.gtif`
- **Description**: Georeferenced TIFF format
- **Features**: Full support for multi-band rasters, overviews, compression

### Cloud Optimized GeoTIFF (COG)

- **Extension**: `.tif`, `.tiff`
- **Description**: Cloud-optimized GeoTIFF format
- **Features**: Optimized for cloud storage and streaming
- **Benefits**: Efficient access to large rasters

### Other Formats

- **JPEG2000**: `.jp2`, `.j2k`
- **PNG**: `.png` (with world file)
- **NetCDF**: `.nc`, `.nc4`
- **HDF**: `.hdf`, `.h5`

## Import Methods

### File Upload

Upload raster files directly:

1. Navigate to raster upload page
2. Select file or drag and drop
3. Add optional description
4. Configure import options
5. Click "Upload"

**File Size Limit**: Configurable (default: 100MB+)

### URL Import

Import from web-accessible URLs:

1. Navigate to URL import page
2. Enter raster URL
3. Configure import options
4. Optionally schedule import
5. Click "Import"

### S3 Bucket Import

Import from AWS S3 buckets:

1. Navigate to S3 import page
2. Configure AWS credentials
3. Select bucket and file
4. Configure import mode
5. Click "Import"

**Import Modes**:
- **Serve COG**: Register as remote COG (no download)
- **Download PostGIS**: Download and import to PostGIS

### GeoServer Import

Import from GeoServer WCS:

1. Navigate to GeoServer import page
2. Select workspace and layer
3. Configure import options
4. Click "Import"

## Import Process

### Step 1: File Validation

Raster file is validated:
- Format detection
- GDAL availability check
- File integrity verification
- Metadata extraction

### Step 2: Metadata Extraction

Metadata extracted using GDAL:
- Spatial reference system (SRID)
- Bounding box
- Pixel size
- Band count
- Data type
- NoData values

### Step 3: PostGIS Import

Raster imported into PostGIS using `raster2pgsql`:

```bash
raster2pgsql -s {srid} -t {tile_size} {file} {schema}.{table} | psql
```

**Options**:
- **Tile Size**: Default 256x256 pixels
- **Schema**: Default 'public'
- **Table Name**: Auto-generated or specified
- **SRID**: Detected from file or specified

### Step 4: Registration

Raster registered in system:
- Metadata stored in `aurora_raster_layers` table
- Layer name assigned
- Access permissions set
- Preview generation

## Configuration Options

### Tile Size

Configure raster tiling:
- **256x256**: Default, good for most cases
- **512x512**: Larger tiles, fewer database rows
- **128x128**: Smaller tiles, more database rows

### Import Mode

For S3/URL imports:
- **Serve COG**: Register remote COG, no local storage
- **Download PostGIS**: Download and import to PostGIS

### Compression

Configure raster compression:
- **None**: No compression
- **JPEG**: Lossy compression
- **LZW**: Lossless compression
- **Deflate**: Lossless compression

## Example: GeoTIFF Upload

```bash
# Via API
curl -X POST "https://example.com/raster_upload.php" \
  -F "raster_file=@elevation.tif" \
  -F "description=Digital elevation model" \
  -F "tile_size=256x256"
```

## Example: S3 Import

```bash
# Via API
curl -X POST "https://example.com/raster_bucket_import_api.php" \
  -d "url=s3://bucket/path/to/raster.tif" \
  -d "mode=download_postgis" \
  -d "aws_access_key_id=..." \
  -d "aws_secret_access_key=..."
```

## Cloud Optimized GeoTIFF (COG)

COG format provides:
- **Efficient Streaming**: Access specific regions without full download
- **Cloud Storage**: Optimized for S3, Azure, GCS
- **Performance**: Fast access to large rasters
- **Cost Effective**: Reduced bandwidth usage

### Creating COGs

Use GDAL to create COG:

```bash
gdal_translate input.tif output.tif \
  -of COG \
  -co COMPRESS=LZW \
  -co TILED=YES
```

## Troubleshooting

### Common Issues

**GDAL not available**
- Install GDAL: `apt-get install gdal-bin` (Ubuntu)
- Verify: `gdalinfo --version`
- Check PATH configuration

**Large file timeout**
- Increase PHP execution time
- Use background import
- Consider chunked upload

**SRID not detected**
- Check raster metadata
- Specify SRID manually
- Verify projection information

**Memory issues**
- Increase PHP memory limit
- Use tile-based processing
- Consider resampling large rasters

## Related Documentation

- [Vector Import](vector.md)
- [PostGIS Import](postgis.md)
- [ESRI Import](esri.md)
- [Raster Analysis Tools](../analysis-tools/raster-histogram.md)