# OversightML Tile Server
The OversightML Tile Server (TS) is a lightweight, cloud-based tile server which provides RESTful APIs for accessing
pixels and metadata for imagery stored in the cloud. Key features include:
* Works with imagery conforming to [Cloud Optimized GeoTIFF (COG)](https://www.cogeo.org/) and [National Imagery Transmission Format (NITF)](https://en.wikipedia.org/wiki/National_Imagery_Transmission_Format) standards
* Creates both orthophoto map and unwarped image tiles. Map tiles are produced by on-the-fly warping of a raw input image pyramid.
* Outputs images in PNG, TIFF, JPEG formats. Can also output NITFs for tiles without warping
* Conforms to [OGC API - Tiles](https://ogcapi.ogc.org/tiles/) specification
## Table of Contents
* [Getting Started](#getting-started)
* [Package Layout](#package-layout)
* [Prerequisites](prerequisites)
* [Running Tile Server Locally](#running-tile-server-locally)
* [Support & Feedback](#support--feedback)
* [Security](#security)
* [License](#license)
## Getting Started
### Package Layout
* **/src**: This is the Python implementation of this application.
* **/test**: Unit tests have been implemented using [pytest](https://docs.pytest.org).
* **/doc**: Contains Sphinx Doc configuration which is used to generate documentation for this package
* **/load-test**: Contains sample [Locust](https://locust.io) configuration files which is used to run load test against the Tile Server
### Documentation
* **APIs**: You can find API documentation for the OSML Tile Server hosted on our [GitHub project page](https://aws-solutions-library-samples.github.io/osml-tile-server/). Keep in mind that the `Try it out` button functionality does not work in Github project page.
* Alternatively, if you are working from the source code running docker build, you can find the latest API documentation by booting up the Tile Server by visiting http://0.0.0.0:8080/latest/docs or http://0.0.0.0:8080/latest/redoc. With this approach, you can use `Try it out` functionality.
### Prerequisites
First, ensure you have installed the following tools locally
- [docker](https://www.docker.com/)
- [docker compose](https://docs.docker.com/compose/)
- [tox](https://tox.wiki/en/latest/installation.html)
### Cloning the repository
Clone the repository to your local computer using
```git clone https://github.com/aws-solutions-library-samples/osml-tile-server.git```
Navigate to the cloned directory using ```cd``` or ```dir```, depending on your operating system.
More information about cloning and managing repositories can be found in the [GitHub Docs](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository).
### Building the Infrastructure
Tile Server infrastructure is contained in the [associated CDK repository](https://github.com/aws-solutions-library-samples/osml-cdk-constructs),
and a sample can be deployed by following the instructions in the [Guidance for Overhead Imagery Inference on AWS repository](https://github.com/aws-solutions-library-samples/guidance-for-overhead-imagery-inference-on-aws).
### Running Tile Server Locally
The Tile Server is designed to be able to be run locally using docker compose for development and testing purposes
using docker compose.
*Note*: Some operating systems may use ```docker-compose``` instead of ```docker compose ```.
Configure your [AWS credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html)
for the account in which the Tile Server infrastructure was deployed by setting your environment variables.
```
export AWS_DEFAULT_REGION=<region where TS infrastructure deployed in>
export AWS_ACCESS_KEY_ID=<AKIAIOSFODNN7EXAMPLE>
export AWS_SECRET_ACCESS_KEY=<wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY>
```
Start the Tile Server using
```shell
docker compose up -d
```
To view the live log output while the server is running
```shell
docker logs -f osml-tile-server
```
To stop the tile server
```shell
docker compose down
```
To rebuild the docker image after making a code change, use
```shell
docker compose up -d --build
```
In another terminal to invoke the rest server and return the viewpoint on a single image, run the following command:
```bash
curl -X 'POST' \
'http://localhost:8080/latest/viewpoints/' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"bucket_name": "<S3 Bucket>",
"object_key": "<Image Name>",
"viewpoint_name": "test",
"tile_size": 512,
"range_adjustment": "NONE"
}'
```
Additionally, you can head over to FastAPI homepage and be able to execute various of API calls by visiting
```
http://0.0.0.0:8080/latest/docs or http://0.0.0.0:8080/latest/redoc
```
## Support & Feedback
To post feedback, submit feature ideas, or report bugs, please use the [Issues](https://github.com/aws-solutions-library-samples/osml-tile-server/issues) section of this GitHub repo.
If you are interested in contributing to OversightML Model Runner, see the [CONTRIBUTING](CONTRIBUTING.md) guide.
## Security
See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
## License
This library is licensed under the MIT-0 License. See the [LICENSE](LICENSE) file.
Raw data
{
"_id": null,
"home_page": null,
"name": "osml-tile-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Amazon Web Services",
"author_email": "aws-osml-admin@amazon.com",
"download_url": "https://files.pythonhosted.org/packages/4f/0c/a7190661e3a72c0655838830d02ee337cbd22eb3698b65a40291fdd240d2/osml_tile_server-0.3.0.tar.gz",
"platform": null,
"description": "# OversightML Tile Server\n\nThe OversightML Tile Server (TS) is a lightweight, cloud-based tile server which provides RESTful APIs for accessing\npixels and metadata for imagery stored in the cloud. Key features include:\n* Works with imagery conforming to [Cloud Optimized GeoTIFF (COG)](https://www.cogeo.org/) and [National Imagery Transmission Format (NITF)](https://en.wikipedia.org/wiki/National_Imagery_Transmission_Format) standards\n* Creates both orthophoto map and unwarped image tiles. Map tiles are produced by on-the-fly warping of a raw input image pyramid.\n* Outputs images in PNG, TIFF, JPEG formats. Can also output NITFs for tiles without warping\n* Conforms to [OGC API - Tiles](https://ogcapi.ogc.org/tiles/) specification\n\n## Table of Contents\n* [Getting Started](#getting-started)\n * [Package Layout](#package-layout)\n * [Prerequisites](prerequisites)\n * [Running Tile Server Locally](#running-tile-server-locally)\n* [Support & Feedback](#support--feedback)\n* [Security](#security)\n* [License](#license)\n\n## Getting Started\n\n### Package Layout\n\n* **/src**: This is the Python implementation of this application.\n* **/test**: Unit tests have been implemented using [pytest](https://docs.pytest.org).\n* **/doc**: Contains Sphinx Doc configuration which is used to generate documentation for this package\n* **/load-test**: Contains sample [Locust](https://locust.io) configuration files which is used to run load test against the Tile Server\n\n### Documentation\n\n* **APIs**: You can find API documentation for the OSML Tile Server hosted on our [GitHub project page](https://aws-solutions-library-samples.github.io/osml-tile-server/). Keep in mind that the `Try it out` button functionality does not work in Github project page.\n * Alternatively, if you are working from the source code running docker build, you can find the latest API documentation by booting up the Tile Server by visiting http://0.0.0.0:8080/latest/docs or http://0.0.0.0:8080/latest/redoc. With this approach, you can use `Try it out` functionality.\n\n### Prerequisites\n\nFirst, ensure you have installed the following tools locally\n\n- [docker](https://www.docker.com/)\n- [docker compose](https://docs.docker.com/compose/)\n- [tox](https://tox.wiki/en/latest/installation.html)\n\n### Cloning the repository\nClone the repository to your local computer using\n\n```git clone https://github.com/aws-solutions-library-samples/osml-tile-server.git```\n\nNavigate to the cloned directory using ```cd``` or ```dir```, depending on your operating system.\n\nMore information about cloning and managing repositories can be found in the [GitHub Docs](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository).\n\n### Building the Infrastructure\nTile Server infrastructure is contained in the [associated CDK repository](https://github.com/aws-solutions-library-samples/osml-cdk-constructs),\nand a sample can be deployed by following the instructions in the [Guidance for Overhead Imagery Inference on AWS repository](https://github.com/aws-solutions-library-samples/guidance-for-overhead-imagery-inference-on-aws).\n\n### Running Tile Server Locally\n\nThe Tile Server is designed to be able to be run locally using docker compose for development and testing purposes\nusing docker compose.\n\n*Note*: Some operating systems may use ```docker-compose``` instead of ```docker compose ```.\n\nConfigure your [AWS credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html)\nfor the account in which the Tile Server infrastructure was deployed by setting your environment variables.\n```\nexport AWS_DEFAULT_REGION=<region where TS infrastructure deployed in>\nexport AWS_ACCESS_KEY_ID=<AKIAIOSFODNN7EXAMPLE>\nexport AWS_SECRET_ACCESS_KEY=<wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY>\n```\n\n\nStart the Tile Server using\n```shell\ndocker compose up -d\n```\n\nTo view the live log output while the server is running\n```shell\ndocker logs -f osml-tile-server\n```\n\nTo stop the tile server\n```shell\ndocker compose down\n```\n\nTo rebuild the docker image after making a code change, use\n```shell\ndocker compose up -d --build\n```\n\nIn another terminal to invoke the rest server and return the viewpoint on a single image, run the following command:\n\n```bash\ncurl -X 'POST' \\\n 'http://localhost:8080/latest/viewpoints/' \\\n -H 'accept: application/json' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"bucket_name\": \"<S3 Bucket>\",\n \"object_key\": \"<Image Name>\",\n \"viewpoint_name\": \"test\",\n \"tile_size\": 512,\n \"range_adjustment\": \"NONE\"\n}'\n```\n\nAdditionally, you can head over to FastAPI homepage and be able to execute various of API calls by visiting\n\n```\nhttp://0.0.0.0:8080/latest/docs or http://0.0.0.0:8080/latest/redoc\n```\n\n## Support & Feedback\n\nTo post feedback, submit feature ideas, or report bugs, please use the [Issues](https://github.com/aws-solutions-library-samples/osml-tile-server/issues) section of this GitHub repo.\n\nIf you are interested in contributing to OversightML Model Runner, see the [CONTRIBUTING](CONTRIBUTING.md) guide.\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis library is licensed under the MIT-0 License. See the [LICENSE](LICENSE) file.\n",
"bugtrack_url": null,
"license": " \u00a9 2023 Amazon Web Services, Inc. or its affiliates. All Rights Reserved. This AWS Content is provided subject to the terms of the AWS Customer Agreement available at http://aws.amazon.com/agreement or other written agreement between Customer and either Amazon Web Services, Inc. or Amazon Web Services EMEA SARL or both.",
"summary": "The OversightML Tile Server is a lightweight, cloud-based tile server which allows you to quickly pass an image from S3 bucket to get metadata, image statistics, and set of tiles in real-time.",
"version": "0.3.0",
"project_urls": {
"Source": "https://github.com/aws-solutions-library-samples/osml-tile-server",
"Tracker": "https://github.com/aws-solutions-library-samples/osml-tile-server/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0ca9cfb57bbdb9387192a2723dac9e88f13cf5f92ff389c077e8a7acd8712366",
"md5": "dd4d0e15b69efba9fc6dd72320f61422",
"sha256": "70436ddda20725f96d0cfc71452a429404e9e8b98b3ada6e50a62ebe7fc0fbf4"
},
"downloads": -1,
"filename": "osml_tile_server-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dd4d0e15b69efba9fc6dd72320f61422",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 38444,
"upload_time": "2024-08-22T20:05:18",
"upload_time_iso_8601": "2024-08-22T20:05:18.122976Z",
"url": "https://files.pythonhosted.org/packages/0c/a9/cfb57bbdb9387192a2723dac9e88f13cf5f92ff389c077e8a7acd8712366/osml_tile_server-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4f0ca7190661e3a72c0655838830d02ee337cbd22eb3698b65a40291fdd240d2",
"md5": "fc7d3fa010fe91803afd3685a0c1dd83",
"sha256": "4231b55b4d935d1335ee35a3994fdf896f706931016894ac49dfc2bcea5398bb"
},
"downloads": -1,
"filename": "osml_tile_server-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "fc7d3fa010fe91803afd3685a0c1dd83",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 33566,
"upload_time": "2024-08-22T20:05:19",
"upload_time_iso_8601": "2024-08-22T20:05:19.530369Z",
"url": "https://files.pythonhosted.org/packages/4f/0c/a7190661e3a72c0655838830d02ee337cbd22eb3698b65a40291fdd240d2/osml_tile_server-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-22 20:05:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws-solutions-library-samples",
"github_project": "osml-tile-server",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "osml-tile-server"
}
JSON
