# STAC Sample Maker
[](https://github.com/developmentseed/stac-sample-maker/actions)
[](https://badge.fury.io/py/stac-sample-maker)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
Generate synthetic [STAC (SpatioTemporal Asset Catalog)](https://stacspec.org/) items with realistic metadata for testing, development, and demonstration purposes.
## Features
- 🌍 **Complete STAC compliance**: Generates valid STAC v1.1.0 items
- 🔧 **All stable extensions**: Supports EO, File, Projection, View, SAR, Scientific, and Landsat extensions
- 📝 **Template-based generation**: Create items matching existing STAC item structures
- ✅ **Schema validation**: Optional validation using stac-validator
- 🎯 **Realistic data**: Uses Faker to generate believable synthetic metadata
- 📊 **Common metadata**: Includes STAC common metadata fields (license, providers, etc.)
- 🔄 **Flexible output**: NDJSON format with stdout or file output
- 🎲 **Reproducible**: Seed support for consistent outputs
## Installation
### Basic Installation
```bash
pip install stac-sample-maker
```
### With Validation Support
```bash
pip install stac-sample-maker[validation]
```
### Development Installation
```bash
git clone https://github.com/developmentseed/stac-sample-maker.git
cd stac-sample-maker
pip install -e ".[dev,validation]"
```
## Quick Start
### Command Line Usage
Generate 5 synthetic STAC items:
```bash
stac-sample-maker --num-items 5
```
Generate items with validation:
```bash
stac-sample-maker --num-items 3 --validate
```
Generate items from a template:
```bash
stac-sample-maker --template my-stac-item.json --num-items 10
```
Save to a file:
```bash
stac-sample-maker --num-items 5 --output samples.ndjson
```
### Library Usage
```python
from stac_sample_maker import generate_stac_items
# Generate basic items
items = generate_stac_items(num_items=5)
# Generate with specific parameters
items = generate_stac_items(
num_items=10,
start_date="2020-01-01T00:00:00Z",
end_date="2023-12-31T23:59:59Z",
bbox=[-122.5, 37.7, -122.3, 37.8], # San Francisco area
seed=42, # For reproducible results
validate=True # Requires stac-validator
)
# Generate from template
from stac_sample_maker import generate_stac_items_from_template
items = generate_stac_items_from_template(
template_path="example-item.json",
num_items=5
)
```
## Command Line Interface
```bash
stac-sample-maker [OPTIONS]
```
### Options
| Option | Description | Default |
|--------|-------------|---------|
| `--num-items N` | Number of STAC items to generate | 1 |
| `--template PATH` | Path to template STAC item JSON file | None |
| `--output PATH` | Output file path (NDJSON format) | stdout |
| `--start DATE` | Start of datetime range (ISO 8601) | None |
| `--end DATE` | End of datetime range (ISO 8601) | None |
| `--interval-percent FLOAT` | Fraction of items using intervals (0-1) | 0.2 |
| `--bbox MINX MINY MAXX MAXY` | Bounding box for geometry | None |
| `--seed INT` | Random seed for reproducibility | None |
| `--validate` | Validate items against STAC schema | False |
### Examples
```bash
# Generate 100 items for 2023 with 50% using time intervals
stac-sample-maker --num-items 100 \
--start "2023-01-01T00:00:00Z" \
--end "2023-12-31T23:59:59Z" \
--interval-percent 0.5
# Generate items within a bounding box (San Francisco)
stac-sample-maker --num-items 20 \
--bbox -122.5 37.7 -122.3 37.8
# Generate reproducible items with validation
stac-sample-maker --num-items 10 \
--seed 42 \
--validate \
--output validated-items.ndjson
```
## Library API
### Core Functions
#### `generate_stac_items()`
Generate synthetic STAC items with all extensions.
```python
def generate_stac_items(
num_items: int,
start_date: Optional[str] = None,
end_date: Optional[str] = None,
interval_percent: float = 0.2,
bbox: Optional[Tuple[float, float, float, float]] = None,
seed: Optional[int] = None,
extensions: Optional[List[str]] = None,
validate: bool = False,
) -> List[dict]:
```
#### `generate_stac_items_from_template()`
Generate STAC items matching a template structure.
```python
def generate_stac_items_from_template(
template_path: str,
num_items: int,
start_date: Optional[str] = None,
end_date: Optional[str] = None,
bbox: Optional[Tuple[float, float, float, float]] = None,
seed: Optional[int] = None,
validate: bool = False,
) -> List[Dict[str, Any]]:
```
#### `validate_stac_item()`
Validate a STAC item against JSON schema.
```python
def validate_stac_item(
item: Dict[str, Any],
strict: bool = True
) -> bool:
```
### Supported Extensions
- **EO (Electro-Optical)**: Cloud cover, snow cover, spectral bands
- **File**: File size, checksums, header information
- **Projection**: EPSG codes, transforms, shapes, bounding boxes
- **View**: Viewing angles, sun position, off-nadir angles
- **SAR**: Radar-specific metadata (frequency, polarization, etc.)
- **Scientific**: DOI citations, publications
- **Landsat**: Landsat-specific metadata (WRS path/row, etc.)
### Template Mode
Template mode analyzes an existing STAC item and generates new items with the same structure:
1. **Extensions**: Matches the exact extensions used
2. **Properties**: Generates new values for the same property fields
3. **Assets**: Creates assets with the same keys and structure
4. **Temporal**: Preserves instant vs. interval temporal patterns
Example template workflow:
```python
# Save one generated item as a template
items = generate_stac_items(num_items=1)
with open("template.json", "w") as f:
json.dump(items[0], f)
# Generate more items matching the template
similar_items = generate_stac_items_from_template(
template_path="template.json",
num_items=100
)
```
## STAC Compliance
Generated items are fully compliant with:
- **STAC Specification v1.1.0**
- **All stable STAC extensions**
- **STAC Common Metadata** (license, providers, platform, etc.)
- **GeoJSON standards** for geometry
- **ISO 8601** for datetime formatting
## Development
### Setup
```bash
git clone https://github.com/developmentseed/stac-sample-maker.git
cd stac-sample-maker
pip install -e ".[dev,validation]"
pre-commit install
```
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=stac_sample_maker --cov-report=html
# Run specific tests
pytest tests/test_generator.py -v
```
### Code Quality
```bash
# Format code
ruff format
# Lint code
ruff check
# Type checking
mypy stac_sample_maker
```
### Pre-commit Hooks
The project uses pre-commit hooks for code quality:
```bash
pre-commit run --all-files
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and linting (`pytest && ruff check && mypy stac_sample_maker`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [STAC Specification](https://stacspec.org/) for the standard
- [Faker](https://faker.readthedocs.io/) for synthetic data generation
- [stac-validator](https://github.com/stac-utils/stac-validator) for validation support
## Related Projects
- [PySTAC](https://pystac.readthedocs.io/) - Python library for working with STAC
- [STAC Validator](https://github.com/stac-utils/stac-validator) - Validation tools
- [STAC Browser](https://github.com/radiantearth/stac-browser) - Browse STAC catalogs
- [STAC Index](https://stacindex.org/) - Discover STAC resources
Raw data
{
"_id": null,
"home_page": null,
"name": "stac-sample-maker",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "geospatial, remote-sensing, satellite, stac, synthetic-data",
"author": null,
"author_email": "David Bitner <bitner@dbspatial.com>",
"download_url": "https://files.pythonhosted.org/packages/13/92/e0ec1a40e434cbccb8333c625194525802bad7b700de1c5d8150495c541c/stac_sample_maker-0.0.2.tar.gz",
"platform": null,
"description": "# STAC Sample Maker\n\n[](https://github.com/developmentseed/stac-sample-maker/actions)\n[](https://badge.fury.io/py/stac-sample-maker)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nGenerate synthetic [STAC (SpatioTemporal Asset Catalog)](https://stacspec.org/) items with realistic metadata for testing, development, and demonstration purposes.\n\n## Features\n\n- \ud83c\udf0d **Complete STAC compliance**: Generates valid STAC v1.1.0 items\n- \ud83d\udd27 **All stable extensions**: Supports EO, File, Projection, View, SAR, Scientific, and Landsat extensions\n- \ud83d\udcdd **Template-based generation**: Create items matching existing STAC item structures\n- \u2705 **Schema validation**: Optional validation using stac-validator\n- \ud83c\udfaf **Realistic data**: Uses Faker to generate believable synthetic metadata\n- \ud83d\udcca **Common metadata**: Includes STAC common metadata fields (license, providers, etc.)\n- \ud83d\udd04 **Flexible output**: NDJSON format with stdout or file output\n- \ud83c\udfb2 **Reproducible**: Seed support for consistent outputs\n\n## Installation\n\n### Basic Installation\n\n```bash\npip install stac-sample-maker\n```\n\n### With Validation Support\n\n```bash\npip install stac-sample-maker[validation]\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/developmentseed/stac-sample-maker.git\ncd stac-sample-maker\npip install -e \".[dev,validation]\"\n```\n\n## Quick Start\n\n### Command Line Usage\n\nGenerate 5 synthetic STAC items:\n\n```bash\nstac-sample-maker --num-items 5\n```\n\nGenerate items with validation:\n\n```bash\nstac-sample-maker --num-items 3 --validate\n```\n\nGenerate items from a template:\n\n```bash\nstac-sample-maker --template my-stac-item.json --num-items 10\n```\n\nSave to a file:\n\n```bash\nstac-sample-maker --num-items 5 --output samples.ndjson\n```\n\n### Library Usage\n\n```python\nfrom stac_sample_maker import generate_stac_items\n\n# Generate basic items\nitems = generate_stac_items(num_items=5)\n\n# Generate with specific parameters\nitems = generate_stac_items(\n num_items=10,\n start_date=\"2020-01-01T00:00:00Z\",\n end_date=\"2023-12-31T23:59:59Z\",\n bbox=[-122.5, 37.7, -122.3, 37.8], # San Francisco area\n seed=42, # For reproducible results\n validate=True # Requires stac-validator\n)\n\n# Generate from template\nfrom stac_sample_maker import generate_stac_items_from_template\n\nitems = generate_stac_items_from_template(\n template_path=\"example-item.json\",\n num_items=5\n)\n```\n\n## Command Line Interface\n\n```bash\nstac-sample-maker [OPTIONS]\n```\n\n### Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--num-items N` | Number of STAC items to generate | 1 |\n| `--template PATH` | Path to template STAC item JSON file | None |\n| `--output PATH` | Output file path (NDJSON format) | stdout |\n| `--start DATE` | Start of datetime range (ISO 8601) | None |\n| `--end DATE` | End of datetime range (ISO 8601) | None |\n| `--interval-percent FLOAT` | Fraction of items using intervals (0-1) | 0.2 |\n| `--bbox MINX MINY MAXX MAXY` | Bounding box for geometry | None |\n| `--seed INT` | Random seed for reproducibility | None |\n| `--validate` | Validate items against STAC schema | False |\n\n### Examples\n\n```bash\n# Generate 100 items for 2023 with 50% using time intervals\nstac-sample-maker --num-items 100 \\\n --start \"2023-01-01T00:00:00Z\" \\\n --end \"2023-12-31T23:59:59Z\" \\\n --interval-percent 0.5\n\n# Generate items within a bounding box (San Francisco)\nstac-sample-maker --num-items 20 \\\n --bbox -122.5 37.7 -122.3 37.8\n\n# Generate reproducible items with validation\nstac-sample-maker --num-items 10 \\\n --seed 42 \\\n --validate \\\n --output validated-items.ndjson\n```\n\n## Library API\n\n### Core Functions\n\n#### `generate_stac_items()`\n\nGenerate synthetic STAC items with all extensions.\n\n```python\ndef generate_stac_items(\n num_items: int,\n start_date: Optional[str] = None,\n end_date: Optional[str] = None,\n interval_percent: float = 0.2,\n bbox: Optional[Tuple[float, float, float, float]] = None,\n seed: Optional[int] = None,\n extensions: Optional[List[str]] = None,\n validate: bool = False,\n) -> List[dict]:\n```\n\n#### `generate_stac_items_from_template()`\n\nGenerate STAC items matching a template structure.\n\n```python\ndef generate_stac_items_from_template(\n template_path: str,\n num_items: int,\n start_date: Optional[str] = None,\n end_date: Optional[str] = None,\n bbox: Optional[Tuple[float, float, float, float]] = None,\n seed: Optional[int] = None,\n validate: bool = False,\n) -> List[Dict[str, Any]]:\n```\n\n#### `validate_stac_item()`\n\nValidate a STAC item against JSON schema.\n\n```python\ndef validate_stac_item(\n item: Dict[str, Any],\n strict: bool = True\n) -> bool:\n```\n\n### Supported Extensions\n\n- **EO (Electro-Optical)**: Cloud cover, snow cover, spectral bands\n- **File**: File size, checksums, header information\n- **Projection**: EPSG codes, transforms, shapes, bounding boxes\n- **View**: Viewing angles, sun position, off-nadir angles\n- **SAR**: Radar-specific metadata (frequency, polarization, etc.)\n- **Scientific**: DOI citations, publications\n- **Landsat**: Landsat-specific metadata (WRS path/row, etc.)\n\n### Template Mode\n\nTemplate mode analyzes an existing STAC item and generates new items with the same structure:\n\n1. **Extensions**: Matches the exact extensions used\n2. **Properties**: Generates new values for the same property fields\n3. **Assets**: Creates assets with the same keys and structure\n4. **Temporal**: Preserves instant vs. interval temporal patterns\n\nExample template workflow:\n\n```python\n# Save one generated item as a template\nitems = generate_stac_items(num_items=1)\nwith open(\"template.json\", \"w\") as f:\n json.dump(items[0], f)\n\n# Generate more items matching the template\nsimilar_items = generate_stac_items_from_template(\n template_path=\"template.json\",\n num_items=100\n)\n```\n\n## STAC Compliance\n\nGenerated items are fully compliant with:\n\n- **STAC Specification v1.1.0**\n- **All stable STAC extensions**\n- **STAC Common Metadata** (license, providers, platform, etc.)\n- **GeoJSON standards** for geometry\n- **ISO 8601** for datetime formatting\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/developmentseed/stac-sample-maker.git\ncd stac-sample-maker\npip install -e \".[dev,validation]\"\npre-commit install\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=stac_sample_maker --cov-report=html\n\n# Run specific tests\npytest tests/test_generator.py -v\n```\n\n### Code Quality\n\n```bash\n# Format code\nruff format\n\n# Lint code\nruff check\n\n# Type checking\nmypy stac_sample_maker\n```\n\n### Pre-commit Hooks\n\nThe project uses pre-commit hooks for code quality:\n\n```bash\npre-commit run --all-files\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests and linting (`pytest && ruff check && mypy stac_sample_maker`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [STAC Specification](https://stacspec.org/) for the standard\n- [Faker](https://faker.readthedocs.io/) for synthetic data generation\n- [stac-validator](https://github.com/stac-utils/stac-validator) for validation support\n\n## Related Projects\n\n- [PySTAC](https://pystac.readthedocs.io/) - Python library for working with STAC\n- [STAC Validator](https://github.com/stac-utils/stac-validator) - Validation tools\n- [STAC Browser](https://github.com/radiantearth/stac-browser) - Browse STAC catalogs\n- [STAC Index](https://stacindex.org/) - Discover STAC resources\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate synthetic STAC (SpatioTemporal Asset Catalog) items with realistic metadata",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/developmentseed/stac-sample-maker",
"Issues": "https://github.com/developmentseed/stac-sample-maker/issues",
"Repository": "https://github.com/developmentseed/stac-sample-maker"
},
"split_keywords": [
"geospatial",
" remote-sensing",
" satellite",
" stac",
" synthetic-data"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "94f236c21e40435f2b30f9f728838e4f0830331c6639d134f51a688254d5a43f",
"md5": "80c878e324c0c46ff67989f4a0f92657",
"sha256": "245f2ab29749f126ed932c0c734b6fe8e6d241edb75270c3d2e6d65da4c22b79"
},
"downloads": -1,
"filename": "stac_sample_maker-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "80c878e324c0c46ff67989f4a0f92657",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 22230,
"upload_time": "2025-08-21T16:22:38",
"upload_time_iso_8601": "2025-08-21T16:22:38.694234Z",
"url": "https://files.pythonhosted.org/packages/94/f2/36c21e40435f2b30f9f728838e4f0830331c6639d134f51a688254d5a43f/stac_sample_maker-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1392e0ec1a40e434cbccb8333c625194525802bad7b700de1c5d8150495c541c",
"md5": "657b21402a2fb0436e9e7c8555d2244c",
"sha256": "2817058891ebd1f8959763625ec9c7a2365caa5bfd80b71177e48503d47388a0"
},
"downloads": -1,
"filename": "stac_sample_maker-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "657b21402a2fb0436e9e7c8555d2244c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 26297,
"upload_time": "2025-08-21T16:22:39",
"upload_time_iso_8601": "2025-08-21T16:22:39.994356Z",
"url": "https://files.pythonhosted.org/packages/13/92/e0ec1a40e434cbccb8333c625194525802bad7b700de1c5d8150495c541c/stac_sample_maker-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 16:22:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "developmentseed",
"github_project": "stac-sample-maker",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "stac-sample-maker"
}
JSON
