examples/inference.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "## City Grid\n",
    "\n",
    "Tile2Net creates a grid of the bounding box of the input city following the Web Map Tile Service (WMTS) standards. You can access both grid level information, as well information about each individual tiles. This grid is used to download tiles, stitch every n tiles together, stitich all tiles in the bounding box to create a large image, among other operations\n",
    "\n",
    "#### To create the data object for your region, you need to pass:\n",
    "<strong>location</strong>: The textual address or bounding box coordinates for your region (e.g. 'Washington square park, Manhattan, NY, USA' ), or a list of coordinates in the form [lat, lon, lat, lon].\n",
    "\n",
    "#### Optional parameters:\n",
    "<strong>input_dir</strong>: The path to the input directory, implicating the format of the files, containing the xtile, ytile, and extension, and possibly containing the zoom level, e.g. `path/to/tiles/z/x/y.ext` or `path/to/tiles/x_y.ext`; If not specified, the tiles will be downloaded from a remote source. If input_dir is passed, the zoom must be passed as well.\n",
    "\n",
    "<strong>output_dir</strong>: The directory where you want to save your data. If not specified, the data will be saved in a folder under your system's temp directory.\n",
    "\n",
    "<strong>name</strong>: Choose a name for your project-region; this name will be used as the base name of the folders for your data.\n",
    "\n",
    "<strong>The remaining attributes are not particularly important for the purposes of this tutorial:</strong>\n",
    "\n",
    "<strong>base_tilesize</strong>: The size of the tiles in pixels. The default is 256, which is the standard size for Web Map Tile Services.\n",
    "\n",
    "<strong>zoom</strong>: The zoom level of the tiles. The default is 19, which is high enough for the required details to be captured wit our tool.\n",
    "\n",
    "<strong>crs</strong>: The coordinate reference system of the tiles. The default is 4326, which is the coordinate reference system for WGS84.\n",
    "\n",
    "<strong>stitch_step</strong>: The number of tiles to stitch together. The default is 1, which means that no stitching will occur. If you want to stitch every 2 tiles together, you would pass 2. If you want to stitch every 4 tiles together, you would pass 4.\n",
    "\n",
    "<strong>boundary_path</strong>: The path to a shapefile that will be used to filter out tiles that are outside the boundary of the shapefile.\n",
    "\n",
    "<strong>padding</strong>: Whether or not to pad the tiles. The default is True, which means that the tiles will be padded to the size of the base_tilesize. If you want to use the original size of the tiles, you would pass False.\n",
    "\n",
    "<strong>extension</strong>: The extension of the tiles. The default is 'png', which is the standard extension for Web Map Tile Services.\n",
    "\n",
    "<strong>dump_percent</strong>: The percent of segmentation images to dump to the subdirectory 'segmentation/seg_results': 100 means all, 0 means none. The default is 0.\n"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "from tile2net import Raster\n"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "### Location\n",
    "You may define the location in two different ways. You may either pass an address, or you may pass a bounding box consisting of two points in latitude, longitude format:"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "location = 'Boston Common, Boston, MA, US'\n",
    "location = \"42.35555189953313, -71.07168915322092, 42.35364837213307, -71.06437423368418\""
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "You may also instantiate a Raster using a local directory of tiles, given that an arbitrary directory structure e.g. `path/to/tiles/z/x/y.ext` or `path/to/tiles/z/x_y.ext` is defined. \n",
    "The `z` for `zoom` may or may not be included in the path, but `zoom` must be passed to the Raster arguments.\n",
    "For instance, if the path to one of my tiles is : `/home/t2n/parks/19/158638/193925.png` , I should pass `/home/t2n/parks/19/x/y.png` where x and y are the x and y of the tiles in the XYZ tile system explained in [this guide](https://github.com/VIDA-NYU/tile2net/blob/main/DATA_PREPARE.md). This is the default format of QGIS tilling outputs as well. "
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "raster = Raster(\n",
    "    location=location,\n",
    "    name='BostonCommon',\n",
    "    # input_dir='<path/to/tiles/z/x/y.png>',\n",
    "    zoom=19,\n",
    ")\n",
    "raster"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "Without specifying `input_dir`, Raster will determine the most suitable tile source for the location, if the region is suppored. \n",
    "If the region is not supported, you can still create a Raster object for your region to work with for some basic tasks but you wont be able to download tile and generate network. "
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "raster = Raster(\n",
    "    location=location,\n",
    "    name='boston common',\n",
    "    output_dir='./example_dir',\n",
    ")\n",
    "raster"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "### Tiles\n",
    "The raster is composed of tiles. You can access a particular tile to view its information, or you can access the entire grid of tiles."
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "raster.tiles[0]"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "### Project Structure\n",
    "You may view the file structure of the project and its resources by accessing the project attribute."
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "raster.project"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "You may also programmatically access project-specific paths by accessing project subattributes."
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "raster.project.tiles.stitched"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "### Generate\n",
    "To begin the inference, we need larger images than what are typically available from Web Map Tile sources. We will stitch together tiles from larger zooms to create high-resolution, stitched images. If the tiles are from a remote source, tile2net will handle the downloads. If the tiles are from a local source, tile2net requires that the tiles' (x, y, z) format is specified with the `input_dir` argument and follow the Web Map Tile Service (WMTS) standards."
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false,
    "pycharm": {
     "is_executing": true
    }
   },
   "source": [
    "raster.generate(4)"
   ],
   "outputs": [],
   "execution_count": null
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "### Inference\n",
    "Now that the tiles have been stitched together, we can run an inference on the stitched images. \n"
   ]
  },
  {
   "cell_type": "code",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "raster.inference()"
   ],
   "outputs": [],
   "execution_count": null
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "t2ne",
   "language": "python",
   "name": "t2ne"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}