{"id":13734047,"url":"https://github.com/yannforget/pylandsat","last_synced_at":"2025-07-29T18:31:08.391Z","repository":{"id":33194002,"uuid":"148338639","full_name":"yannforget/pylandsat","owner":"yannforget","description":"Search, download, and preprocess Landsat imagery 🛰️","archived":false,"fork":false,"pushed_at":"2023-06-07T09:04:13.000Z","size":68,"stargazers_count":65,"open_issues_count":10,"forks_count":18,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-12T23:35:49.604Z","etag":null,"topics":["earth-observation","gis","landsat","remote-sensing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yannforget.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-09-11T15:26:15.000Z","updated_at":"2024-03-22T01:22:43.000Z","dependencies_parsed_at":"2022-07-16T07:46:56.994Z","dependency_job_id":null,"html_url":"https://github.com/yannforget/pylandsat","commit_stats":{"total_commits":65,"total_committers":4,"mean_commits":16.25,"dds":0.0461538461538461,"last_synced_commit":"9e65126d010a29e025c16318a55f9b0234e4ae80"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yannforget%2Fpylandsat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yannforget%2Fpylandsat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yannforget%2Fpylandsat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yannforget%2Fpylandsat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yannforget","download_url":"https://codeload.github.com/yannforget/pylandsat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228034977,"owners_count":17859245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["earth-observation","gis","landsat","remote-sensing"],"created_at":"2024-08-03T03:00:52.030Z","updated_at":"2024-12-04T03:11:18.962Z","avatar_url":"https://github.com/yannforget.png","language":"Python","funding_links":[],"categories":["`Python` processing of optical imagery (non deep learning)"],"sub_categories":["Download"],"readme":"[![Build](https://img.shields.io/github/workflow/status/yannforget/pylandsat/Publish%20package?label=build\u0026logo=github)](https://github.com/yannforget/pylandsat/actions/workflows/publish-to-pypi.yml)\n[![Tests](https://img.shields.io/github/workflow/status/yannforget/pylandsat/Run%20tests?label=tests\u0026logo=github)](https://github.com/yannforget/pylandsat/actions/workflows/run-tests.yml)\n[![codecov](https://codecov.io/gh/yannforget/pylandsat/branch/master/graph/badge.svg?token=YB1XC4TKX3)](https://codecov.io/gh/yannforget/pylandsat)\n[![DOI](https://zenodo.org/badge/148338639.svg)](https://zenodo.org/badge/latestdoi/148338639)\n\n# Description\n\n**pylandsat** is a Python package that allows you to search and download\nLandsat scenes from the public dataset hosted on\n[Google Cloud](https://cloud.google.com/storage/docs/public-datasets/landsat).\nAdditionally, it includes a set of classes and methods to access and\npreprocess the downloaded scenes.\n\nOnly Landsat [Collection 1](https://landsat.usgs.gov/landsat-collections) is supported, i.e. level-1 data products from the following sensors and satellite missions:\n\n* Landsat 8 OLI/TIRS\n* Landsat 7 ETM+\n* Landsat 4-5 TM\n* Landsat 1-5 MSS\n\n# Installation\n\n`pip install pylandsat`\n\n# Command-line interface\n\n## Download one or multiple scenes\n\n### Usage\n\n```bash\nUsage: pylandsat download [OPTIONS] [PRODUCTS]...\n\n  Download a Landsat product according to its identifier.\n\nOptions:\n  -d, --output-dir PATH  Output directory.\n  -f, --files TEXT       Comma-separated list of files to download.\n  --help                 Show this message and exit.\n```\n\n### Examples\n\n```bash\n# Download an entire product in the current directory\npylandsat download LE07_L1TP_205050_19991104_20170216_01_T1\n\n# Download multiple products\npylandsat download \\\n    LE07_L1TP_205050_19991104_20170216_01_T1 \\\n    LE07_L1TP_206050_19991111_20170216_01_T1\n\n# Download only the blue, green and red bands\npylandsat download --files B1.TIF,B2.TIF,B3.TIF \\\n    LE07_L1TP_205050_19991104_20170216_01_T1\n\n# Download only quality band\npylandsat download --files BQA.TIF \\\n    LE07_L1TP_205050_19991104_20170216_01_T1\n```\n\n## Search for scenes\n\nTo allow large and fast queries, **pylandsat** works with a local dump of the Landsat catalog hosted on Google Cloud. As such, an initial sync is required :\n\n```bash\n# Sync local Landsat catalog\npylandsat sync-database\n\n# Force update\npylandsat sync-database -f\n```\n\nThe database is stored in a local directory that can be displayed using the following command :\n\n```bash\npylandsat print-datadir\n```\n\nOnce the database has been created, the local catalog can be queried.\n\n### Usage\n\n```bash\nUsage: pylandsat search [OPTIONS]\n\n  Search for scenes in the Google Landsat Public Dataset catalog.\n\nOptions:\n  -b, --begin TEXT       Begin search date (YYYY-MM-DD).\n  -e, --end TEXT         End search date (YYYY-MM-DD).\n  -g, --geojson PATH     Area of interest (GeoJSON file).\n  -l, --latlon FLOAT...  Point of interest (decimal lat/lon).\n  -p, --path INTEGER     WRS2 path.\n  -r, --row INTEGER      WRS2 row.\n  -c, --clouds FLOAT     Max. cloud cover percentage.\n  -s, --sensors TEXT     Comma-separated list of possible sensors.\n  -t, --tiers TEXT       Comma-separated list of possible collection tiers.\n  --slcoff               Include SLC-off LE7 scenes.\n  -o, --output PATH      Output CSV file.\n  --help                 Show this message and exit.\n```\n\nAt least three options must be provided: `--begin` and `--end` (i.e. the period of interest), and a geographic extent (`--path` and `--row`, `--latlon`, `--address` or `--geojson`). By default, **pylandsat** lists all the product IDs matching the query. The full response can be exported to a CSV file using the `--output` option. Note that is the spatial extent is provided as a GeoJSON file, only the first feature will be considered.\n\n### Examples\n\n```bash\n# If only the year is provided, date is set to January 1st\npylandsat search \\\n    --begin 1999 --end 2000 \\\n    --path 206 --row 50 \\\n    --clouds 0\n\n# Using latitude and longitude\npylandsat search \\\n    --begin 2000 --end 2010 \\\n    --latlon 50.85 4.34\n\n# Using a polygon in a GeoJSON file\npylandsat search \\\n    --begin 2000 --end 2010 \\\n    --geojson brussels.geojson\n\n# Using an address that will be geocoded\npylandsat search \\\n    --begin 2000 --end 2010 \\\n    --address 'Brussels, Belgium'\n\n# Limit to TM and ETM sensors\npylandsat search \\\n    --begin 1990 --end 2010 \\\n    --address 'Brussels, Belgium' \\\n    --sensors LT04,LT05,LE07\n\n# Export results into a CSV file\npylandsat search \\\n    --begin 1990 --end 2010 \\\n    --address 'Brussels, Belgium' \\\n    --sensors LT04,LT05,LE07 \\\n    --output scenes.csv\n```\n\n```bash\n# List available sensors, i.e. possible values\n# for the `--sensors` option\npylandsat list-sensors\n\n# List available files for a given sensor\npylandsat list-available-files LT05\n```\n\n# Python API\n\n## Search the catalog\n\n``` python\nfrom datetime import datetime\n\nfrom shapely.geometry import Point\nfrom pylandsat import Catalog, Product\n\ncatalog = Catalog()\n\nbegin = datetime(2010, 1, 1)\nend = datetime(2020, 1, 1)\ngeom = Point(4.34, 50.85)\n\n# Results are returned as a list\nscenes = catalog.search(\n    begin=begin,\n    end=end,\n    geom=geom,\n    sensors=['LE07', 'LC08']\n)\n\n# Get the product ID of the first scene\nproduct_id = scenes[0].get(\"product_id\")\n\n# Download the scene\nproduct = Product(product_id)\nproduct.download(out_dir='data')\n\n# The output of catalog.search() can be converted to a DataFrame\n# for further processing. For instance:\n# Get the product ID of the scene with the lowest cloud cover\nimport pandas as pd\n\ndf = pd.DataFrame.from_dict(scenes)\ndf.set_index([\"product_id\"], inplace=True)\ndf = df.sort_values(by='cloud_cover', ascending=True)\nproduct_id = df.index[0]\n```\n\n## Load and preprocess data\n\n``` python\nimport numpy as np\nimport rasterio\nimport matplotlib.pyplot as plt\nfrom pylandsat import Scene\n\n# Access data\nscene = Scene('data/LE07_L1TP_205050_19991104_20170216_01_T1')\nprint(scene.available_bands())\nprint(scene.product_id)\nprint(scene.sensor)\nprint(scene.date)\n\n# Access MTL metadata\nprint(scene.mtl['IMAGE_ATTRIBUTES']['CLOUD_COVER_LAND'])\n\n# Quality band\nplt.imshow(scene.quality.read())\n\n# Access band data\nnir = scene.nir.read(1)\nred = scene.red.read(1)\nndvi = (nir + red) / (nir - red)\n\n# Access band metadata\nprint(scene.nir.bname)\nprint(scene.nir.fname)\nprint(scene.nir.profile)\nprint(scene.nir.width, scene.nir.height)\nprint(scene.nir.crs)\n\n# Use reflectance values instead of DN\nnir = scene.nir.to_reflectance()\n\n# ..or brightness temperature\ntirs = scene.tirs.to_brightness_temperature()\n\n# Save file to disk\nwith rasterio.open('temperature.tif', 'w', **scene.tirs.profile) as dst:\n    dst.write(tirs, 1)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyannforget%2Fpylandsat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyannforget%2Fpylandsat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyannforget%2Fpylandsat/lists"}