notebooks/src/2-create-stac-catalog-python.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "3fdd73ec",
   "metadata": {},
   "source": [
    "# Create a Basic STAC Catalog Using PySTAC "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "79ba9549",
   "metadata": {},
   "source": [
    "In the [previous tutorial](/en/tutorials/1-read-stac-python/index.html), you learned how to use [PySTAC](https://pystac.readthedocs.io/en/stable/index.html#) to read an existing STAC Catalog. In this tutorial, you will learn how to create your own STAC Catalog (also using PySTAC). By the end, you will have a basic STAC Catalog created. \n",
    "\n",
    "In the following tutorials, you will learn to add additional STAC components and functionality to the basic STAC Catalog you create here. The experience you gain from this tutorial along with the extensive [PySTAC documentation](https://pystac.readthedocs.io/en/latest/api.html) will allow you to create your own STAC Catalog on a different dataset."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e46f9ddd",
   "metadata": {},
   "source": [
    "## Dependencies \n",
    "If you need to install pystac, rasterio, or pystac, uncomment the lines below and run the cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "9871a1e4",
   "metadata": {},
   "outputs": [],
   "source": [
    "# ! pip install pystac\n",
    "# ! pip install rasterio\n",
    "# ! pip install shapely"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9d60330",
   "metadata": {},
   "source": [
    "## Import Packages and Store Data\n",
    "To begin, import the packages and classes that you need to access data and work with STAC Catalogs in Python."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "a7f33f70",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import json\n",
    "import rasterio\n",
    "import urllib.request\n",
    "import pystac\n",
    "\n",
    "from datetime import datetime, timezone\n",
    "from shapely.geometry import Polygon, mapping\n",
    "from tempfile import TemporaryDirectory"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a230a443",
   "metadata": {},
   "source": [
    "To give us some material to work with, let's download a single image from the [SpaceNet 5 Challenge](https://spacenet.ai/sn5-challenge/). We will use a temporary directory to save our single-Item STAC."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "61a2c5b5",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('/var/folders/73/z5lbqv_s6l7fcfx464_pn8p80000gn/T/tmp17i4icyl/image.tif',\n",
       " <http.client.HTTPMessage at 0x116ffa710>)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Set temporary directory to store source data\n",
    "tmp_dir = TemporaryDirectory()\n",
    "img_path = os.path.join(tmp_dir.name, 'image.tif')\n",
    "\n",
    "# Fetch and store data\n",
    "url = ('https://spacenet-dataset.s3.amazonaws.com/'\n",
    "       'spacenet/SN5_roads/train/AOI_7_Moscow/MS/'\n",
    "       'SN5_roads_train_AOI_7_Moscow_MS_chip996.tif')\n",
    "urllib.request.urlretrieve(url, img_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "378daf2c",
   "metadata": {},
   "source": [
    "We want to create a STAC Catalog. Take a look at the [Catalog documentation](https://pystac.readthedocs.io/en/stable/api/catalog.html) to see what information you need to create our PySTAC `Catalog` instance. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fa7474a6",
   "metadata": {},
   "source": [
    "## Create the STAC Catalog\n",
    "\n",
    "Start by first creating the catalog and only populating the required arguments: the ID and description. The remaining arguments will be added to the catalog further along in the tutorial."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "85610df2",
   "metadata": {},
   "outputs": [],
   "source": [
    "catalog = pystac.Catalog(id='tutorial-catalog', description='This catalog is a basic demonstration catalog utilizing a scene from SpaceNet 5.')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "69d2a193",
   "metadata": {},
   "source": [
    "The catalog now exists. Take a look inside. \n",
    "\n",
    "In the Introduction to STAC lesson on this site, you learned about the three main components of the STAC Specification and the possible relations between them all. Based on what you learned and what we have done so far, do you think your catalog has any children or items? Let's take a look:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "a36577e8",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[]\n",
      "[]\n"
     ]
    }
   ],
   "source": [
    "print(list(catalog.get_children()))\n",
    "print(list(catalog.get_items()))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5926b4fd",
   "metadata": {},
   "source": [
    "Since we have not added them, there are no children or items in the catalog yet. We need to add these components."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8078156f",
   "metadata": {},
   "source": [
    "### JSON Progress Check\n",
    "Throughout this tutorial, we will be checking in on the STAC components we are creating using `to_dict()` to see how the STAC JSON is shaping up. Let's take a look at the catalog we just created. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "e6e4fb0e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "    \"type\": \"Catalog\",\n",
      "    \"id\": \"tutorial-catalog\",\n",
      "    \"stac_version\": \"1.0.0\",\n",
      "    \"description\": \"This catalog is a basic demonstration catalog utilizing a scene from SpaceNet 5.\",\n",
      "    \"links\": []\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "print(json.dumps(catalog.to_dict(), indent=4))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b593ebbb",
   "metadata": {},
   "source": [
    "## Create a STAC Item\n",
    "\n",
    "Now that the catalog exists, we can populate it. Let's create a STAC Item to represent the image we saved in the temporary directory. Again, take a look at the [PySTAC Documentation for an Item](https://pystac.readthedocs.io/en/stable/api/item.html#pystac-item) to see what you need to supply.\n",
    "\n",
    "For creating this item, you will populate all the attributes at once.\n",
    "\n",
    "Let's collect the information we need for each attribute."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0fe276b2",
   "metadata": {},
   "source": [
    "### Collect the Item's `geometry` and `bbox`\n",
    "Using [rasterio](https://rasterio.readthedocs.io/en/stable/), we can extract the image's bounding box and geometry metadata. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "42cff872",
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_bbox_and_footprint(raster):\n",
    "    with rasterio.open(raster) as r:\n",
    "        bounds = r.bounds\n",
    "        bbox = [bounds.left, bounds.bottom, bounds.right, bounds.top]\n",
    "        footprint = Polygon([\n",
    "            [bounds.left, bounds.bottom],\n",
    "            [bounds.left, bounds.top],\n",
    "            [bounds.right, bounds.top],\n",
    "            [bounds.right, bounds.bottom]\n",
    "        ])\n",
    "        \n",
    "        return (bbox, mapping(footprint))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "51622107",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "bbox:  [37.6616853489879, 55.73478197572927, 37.66573047610874, 55.73882710285011] \n",
      "\n",
      "footprint:  {'type': 'Polygon', 'coordinates': (((37.6616853489879, 55.73478197572927), (37.6616853489879, 55.73882710285011), (37.66573047610874, 55.73882710285011), (37.66573047610874, 55.73478197572927), (37.6616853489879, 55.73478197572927)),)}\n"
     ]
    }
   ],
   "source": [
    "# Run the function and print out the results\n",
    "bbox, footprint = get_bbox_and_footprint(img_path)\n",
    "print(\"bbox: \", bbox, \"\\n\")\n",
    "print(\"footprint: \", footprint)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "14440cee",
   "metadata": {},
   "source": [
    "### Collect the Item `datetime`  \n",
    "\n",
    "To obtain the datetime property for our Item from the image, we will use [datetime.now()](https://docs.python.org/3/library/datetime.html#datetime.datetime.now)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "20841064",
   "metadata": {},
   "outputs": [],
   "source": [
    "datetime_utc = datetime.now(tz=timezone.utc)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a2800892",
   "metadata": {},
   "source": [
    "### Populate `pystac.Item`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "2bb0a88d",
   "metadata": {},
   "outputs": [],
   "source": [
    "item = pystac.Item(id='local-image',\n",
    "                 geometry=footprint,\n",
    "                 bbox=bbox,\n",
    "                 datetime=datetime_utc,\n",
    "                 properties={})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "09a91925",
   "metadata": {},
   "source": [
    "Now we have our first Item.\n",
    "\n",
    "However, the item has not been added to our catalog yet. Therefore, when you run the following cell, you can see that the Item does not have a parent yet:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "4765ae18",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "print(item.get_parent() is None)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7ad4f8f4",
   "metadata": {},
   "source": [
    "### Add the Item to the Catalog"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "059cd4fa",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "\n",
       "<style>\n",
       ".pystac-summary {\n",
       "    cursor: pointer;\n",
       "    display:list-item;\n",
       "}\n",
       ".pystac-key {\n",
       "    color: rgb(0, 128, 0);\n",
       "    font-weight: 700;\n",
       "}\n",
       ".pystac-key-value {\n",
       "    display: inline-block;\n",
       "    margin: 0px 0.5em 0px 0px;\n",
       "}\n",
       "</style>\n",
       "<div class=\"jp-RenderedJSON jp-mod-trusted jp-OutputArea-output\">\n",
       "    <div class=\"container\" style=\"line-height: normal;\">\n",
       "        <ul style=\"padding: 0px; margin: 0px; list-style: none; display: block;\">\n",
       "            \n",
       "                \n",
       "                    \n",
       "        <li style=\"overflow-wrap: break-word; padding-left: 2.125em; text-indent: -0.5em;\">\n",
       "            <span class=\"pystac-key pystac-key-value\">rel</span>\n",
       "            <span style=\"color: rgb(186, 33, 33);\">\"item\"</span>\n",
       "        </li>\n",
       "    \n",
       "                \n",
       "            \n",
       "                \n",
       "                    \n",
       "        <li style=\"overflow-wrap: break-word; padding-left: 2.125em; text-indent: -0.5em;\">\n",
       "            <span class=\"pystac-key pystac-key-value\">href</span>\n",
       "            <span style=\"color: rgb(186, 33, 33);\">None</span>\n",
       "        </li>\n",
       "    \n",
       "                \n",
       "            \n",
       "                \n",
       "                    \n",
       "        <li style=\"overflow-wrap: break-word; padding-left: 2.125em; text-indent: -0.5em;\">\n",
       "            <span class=\"pystac-key pystac-key-value\">type</span>\n",
       "            <span style=\"color: rgb(186, 33, 33);\">\"application/json\"</span>\n",
       "        </li>\n",
       "    \n",
       "                \n",
       "            \n",
       "        </ul>\n",
       "    </div>\n",
       "</div>"
      ],
      "text/plain": [
       "<Link rel=item target=<Item id=local-image>>"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "catalog.add_item(item)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7c8ede32",
   "metadata": {},
   "source": [
    "### Visualize the Catalog Relationship"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f3a7ccf9",
   "metadata": {},
   "source": [
    "Now that we have added the item to the catalog, we can see it link to it’s parent (which is the catalog)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "a8327af8",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "\n",
       "<style>\n",
       ".pystac-summary {\n",
       "    cursor: pointer;\n",
       "    display:list-item;\n",
       "}\n",
       ".pystac-key {\n",
       "    color: rgb(0, 128, 0);\n",
       "    font-weight: 700;\n",
       "}\n",
       ".pystac-key-value {\n",
       "    display: inline-block;\n",
       "    margin: 0px 0.5em 0px 0px;\n",
       "}\n",
       "</style>\n",
       "<div class=\"jp-RenderedJSON jp-mod-trusted jp-OutputArea-output\">\n",
       "    <div class=\"container\" style=\"line-height: normal;\">\n",
       "        <ul style=\"padding: 0px; margin: 0px; list-style: none; display: block;\">\n",
       "            \n",
       "                \n",
       "                    \n",
       "        <li style=\"overflow-wrap: break-word; padding-left: 2.125em; text-indent: -0.5em;\">\n",
       "            <span class=\"pystac-key pystac-key-value\">type</span>\n",
       "            <span style=\"color: rgb(186, 33, 33);\">\"Catalog\"</span>\n",
       "        </li>\n",
       "    \n",
       "                \n",
       "            \n",
       "                \n",
       "                    \n",
       "        <li style=\"overflow-wrap: break-word; padding-left: 2.125em; text-indent: -0.5em;\">\n",
       "            <span class=\"pystac-key pystac-key-value\">id</span>\n",
       "            <span style=\"color: rgb(186, 33, 33);\">\"tutorial-catalog\"</span>\n",
       "        </li>\n",
       "    \n",
       "                \n",
       "            \n",
       "                \n",
       "                    \n",
       "        <li style=\"overflow-wrap: break-word; padding-left: 2.125em; text-indent: -0.5em;\">\n",
       "            <span class=\"pystac-key pystac-key-value\">stac_version</span>\n",
       "            <span style=\"color: rgb(186, 33, 33);\">\"1.0.0\"</span>\n",
       "        </li>\n",
       "    \n",
       "                \n",
       "            \n",
       "                \n",
       "                    \n",
       "        <li style=\"overflow-wrap: break-word; padding-left: 2.125em; text-indent: -0.5em;\">\n",
       "            <span class=\"pystac-key pystac-key-value\">description</span>\n",
       "            <span style=\"color: rgb(186, 33, 33);\">\"This catalog is a basic demonstration catalog utilizing a scene from SpaceNet 5.\"</span>\n",
       "        </li>\n",
       "    \n",
       "                \n",
       "            \n",
       "                \n",
       "                    <li><details>\n",
       "        <summary class=\"pystac-summary\">\n",
       "            <span class=\"pystac-key\">links</span>\n",
       "            <span style=\"padding-left: 0.5em; color: rgb(64, 128, 128); font-style: italic;\">[] 1 items</span>\n",
       "        </summary>\n",
       "        \n",
       "            <ul style=\"margin: 0px; padding: 0px 0px 0px 1.75em; list-style: none; display: block;\">\n",
       "        \n",
       "            \n",
       "                \n",
       "        <li><details>\n",
       "            <summary class=\"pystac-summary\"><span class=\"pystac-key\">0</span></summary>\n",
       "            <ul style=\"margin: 0px; padding: 0px 0px 0px 1.75em; list-style: none; display: block;\">\n",
       "        \n",
       "            \n",
       "                \n",
       "        <li style=\"overflow-wrap: break-word; padding-left: 2.125em; text-indent: -0.5em;\">\n",
       "            <span class=\"pystac-key pystac-key-value\">rel</span>\n",
       "            <span style=\"color: rgb(186, 33, 33);\">\"item\"</span>\n",
       "        </li>\n",
       "    \n",
       "            \n",
       "        \n",
       "            \n",
       "                \n",
       "        <li style=\"overflow-wrap: break-word; padding-left: 2.125em; text-indent: -0.5em;\">\n",
       "            <span class=\"pystac-key pystac-key-value\">href</span>\n",
       "            <span style=\"color: rgb(186, 33, 33);\">None</span>\n",
       "        </li>\n",
       "    \n",
       "            \n",
       "        \n",
       "            \n",
       "                \n",
       "        <li style=\"overflow-wrap: break-word; padding-left: 2.125em; text-indent: -0.5em;\">\n",
       "            <span class=\"pystac-key pystac-key-value\">type</span>\n",
       "            <span style=\"color: rgb(186, 33, 33);\">\"application/json\"</span>\n",
       "        </li>\n",
       "    \n",
       "            \n",
       "        \n",
       "    </ul>\n",
       "        </details></li>\n",
       "    \n",
       "            \n",
       "        \n",
       "    </ul>\n",
       "        \n",
       "    </details></li>\n",
       "                \n",
       "            \n",
       "        </ul>\n",
       "    </div>\n",
       "</div>"
      ],
      "text/plain": [
       "<Catalog id=tutorial-catalog>"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "item.get_parent()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "22e64c24",
   "metadata": {},
   "source": [
    "You can also visualize the architecture of the STAC Catalog by using the `describe()` method. As a reminder, **be careful** when using it on large catalogs, as it will walk the entire tree of the STAC."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "e6018434",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "* <Catalog id=tutorial-catalog>\n",
      "  * <Item id=local-image>\n"
     ]
    }
   ],
   "source": [
    "catalog.describe()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e0449833",
   "metadata": {},
   "source": [
    "## Add STAC Assets\n",
    "We’ve created an item, but there aren’t any assets associated with it. Let’s create one. As always, take a look at the [PySTAC API Documentation](https://pystac.readthedocs.io/en/stable/api/asset.html#pystac-asset) to see what components are needed to create an Asset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "983b599e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Add Asset and all its information to Item \n",
    "item.add_asset(\n",
    "    key='image',\n",
    "    asset=pystac.Asset(\n",
    "        href=img_path,\n",
    "        media_type=pystac.MediaType.GEOTIFF\n",
    "    )\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3834c826",
   "metadata": {},
   "source": [
    "#### JSON Progress Check\n",
    "Run `to_dict()` on the STAC Item we created. Notice the asset is now set:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "abb980fb",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "    \"type\": \"Feature\",\n",
      "    \"stac_version\": \"1.0.0\",\n",
      "    \"id\": \"local-image\",\n",
      "    \"properties\": {\n",
      "        \"datetime\": \"2023-10-18T03:10:18.923211Z\"\n",
      "    },\n",
      "    \"geometry\": {\n",
      "        \"type\": \"Polygon\",\n",
      "        \"coordinates\": [\n",
      "            [\n",
      "                [\n",
      "                    37.6616853489879,\n",
      "                    55.73478197572927\n",
      "                ],\n",
      "                [\n",
      "                    37.6616853489879,\n",
      "                    55.73882710285011\n",
      "                ],\n",
      "                [\n",
      "                    37.66573047610874,\n",
      "                    55.73882710285011\n",
      "                ],\n",
      "                [\n",
      "                    37.66573047610874,\n",
      "                    55.73478197572927\n",
      "                ],\n",
      "                [\n",
      "                    37.6616853489879,\n",
      "                    55.73478197572927\n",
      "                ]\n",
      "            ]\n",
      "        ]\n",
      "    },\n",
      "    \"links\": [\n",
      "        {\n",
      "            \"rel\": \"root\",\n",
      "            \"href\": null,\n",
      "            \"type\": \"application/json\"\n",
      "        },\n",
      "        {\n",
      "            \"rel\": \"parent\",\n",
      "            \"href\": null,\n",
      "            \"type\": \"application/json\"\n",
      "        }\n",
      "    ],\n",
      "    \"assets\": {\n",
      "        \"image\": {\n",
      "            \"href\": \"/var/folders/73/z5lbqv_s6l7fcfx464_pn8p80000gn/T/tmp17i4icyl/image.tif\",\n",
      "            \"type\": \"image/tiff; application=geotiff\"\n",
      "        }\n",
      "    },\n",
      "    \"bbox\": [\n",
      "        37.6616853489879,\n",
      "        55.73478197572927,\n",
      "        37.66573047610874,\n",
      "        55.73882710285011\n",
      "    ],\n",
      "    \"stac_extensions\": []\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "print(json.dumps(item.to_dict(), indent=4))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "997845b5",
   "metadata": {},
   "source": [
    "Note that the link href properties are null. The empty href links are OK for now, as we’re working with the STAC in memory. Next, we will write the Catalog out and set those HREFs."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16765d52",
   "metadata": {},
   "source": [
    "## Save the Catalog\n",
    "\n",
    "As the JSON above indicates, there are no HREFs set on these in-memory items. PySTAC uses the `self` link on STAC objects to track where the file lives. Because we haven’t set them, they evaluate to `None`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "a620802d",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "True\n"
     ]
    }
   ],
   "source": [
    "print(catalog.get_self_href() is None)\n",
    "print(item.get_self_href() is None)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5d8d936d",
   "metadata": {},
   "source": [
    "### Set the Catalog's HREFs"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e74ffa1",
   "metadata": {},
   "source": [
    "In order to set the HREFs, we can use `normalize_hrefs`. [This method](https://pystac.readthedocs.io/en/stable/api/pystac.html?highlight=normalize_hrefs#pystac.Catalog.normalize_hrefs) will create a normalized set of HREFs for each STAC object in the catalog, according to the recommendations from the [best practices document](https://github.com/radiantearth/stac-spec/blob/v0.8.1/best-practices.md#catalog-layout) on how to lay out a catalog."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "f77e34ab",
   "metadata": {},
   "outputs": [],
   "source": [
    "catalog.normalize_hrefs(os.path.join(tmp_dir.name, \"stac\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4e07363f",
   "metadata": {},
   "source": [
    "Now that we’ve normalized to a root directory (the temporary directory), we see that the `self` links are set:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "2275eb8e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Catalog HREF:  /var/folders/73/z5lbqv_s6l7fcfx464_pn8p80000gn/T/tmp17i4icyl/stac/catalog.json\n",
      "Item HREF:  /var/folders/73/z5lbqv_s6l7fcfx464_pn8p80000gn/T/tmp17i4icyl/stac/local-image/local-image.json\n"
     ]
    }
   ],
   "source": [
    "print(\"Catalog HREF: \", catalog.get_self_href())\n",
    "print(\"Item HREF: \", item.get_self_href())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9382be83",
   "metadata": {},
   "source": [
    "We can now call [`save`](https://pystac.readthedocs.io/en/stable/api/pystac.html?highlight=normalize_hrefs#pystac.Catalog.save) on the catalog, which will recursively save all the STAC objects to their respective self HREFs.\n",
    "\n",
    "Save requires a `CatalogType` to be set. You can review the [PySTAC API Documentation](https://pystac.readthedocs.io/en/stable/api/pystac.html?highlight=CatalogType#catalogtype) to learn about each `CatalogType`.\n",
    "\n",
    "Here, we will be creating a ‘self-contained catalog.' This type is one that is designed for portability. Users may want to download an online catalog from and be able to use it on their local computer, so all links need to be relative."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "55119cfd",
   "metadata": {},
   "source": [
    "### Save the Catalog: Self Contained "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "14d03aee",
   "metadata": {},
   "outputs": [],
   "source": [
    "catalog.save(catalog_type=pystac.CatalogType.SELF_CONTAINED)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb241b14",
   "metadata": {},
   "source": [
    "Take a look at the temporary directory to see the catalog and item."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "8db68123",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "/var/folders/73/z5lbqv_s6l7fcfx464_pn8p80000gn/T/tmp17i4icyl/stac/catalog.json\r\n",
      "\r\n",
      "/var/folders/73/z5lbqv_s6l7fcfx464_pn8p80000gn/T/tmp17i4icyl/stac/local-image:\r\n",
      "local-image.json\r\n"
     ]
    }
   ],
   "source": [
    "!ls {tmp_dir.name}/stac/*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e7fc026c",
   "metadata": {},
   "source": [
    "Now that our Catalog has been written out to file, we can open it up and read it directly. We should see the previously null hrefs populated with paths to the respective STAC component. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "1cdd135d",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "  \"type\": \"Catalog\",\n",
      "  \"id\": \"tutorial-catalog\",\n",
      "  \"stac_version\": \"1.0.0\",\n",
      "  \"description\": \"This catalog is a basic demonstration catalog utilizing a scene from SpaceNet 5.\",\n",
      "  \"links\": [\n",
      "    {\n",
      "      \"rel\": \"root\",\n",
      "      \"href\": \"./catalog.json\",\n",
      "      \"type\": \"application/json\"\n",
      "    },\n",
      "    {\n",
      "      \"rel\": \"item\",\n",
      "      \"href\": \"./local-image/local-image.json\",\n",
      "      \"type\": \"application/json\"\n",
      "    }\n",
      "  ]\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "with open(catalog.self_href) as f:\n",
    "    print(f.read())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "3d064086",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "  \"type\": \"Feature\",\n",
      "  \"stac_version\": \"1.0.0\",\n",
      "  \"id\": \"local-image\",\n",
      "  \"properties\": {\n",
      "    \"datetime\": \"2023-10-18T03:10:18.923211Z\"\n",
      "  },\n",
      "  \"geometry\": {\n",
      "    \"type\": \"Polygon\",\n",
      "    \"coordinates\": [\n",
      "      [\n",
      "        [\n",
      "          37.6616853489879,\n",
      "          55.73478197572927\n",
      "        ],\n",
      "        [\n",
      "          37.6616853489879,\n",
      "          55.73882710285011\n",
      "        ],\n",
      "        [\n",
      "          37.66573047610874,\n",
      "          55.73882710285011\n",
      "        ],\n",
      "        [\n",
      "          37.66573047610874,\n",
      "          55.73478197572927\n",
      "        ],\n",
      "        [\n",
      "          37.6616853489879,\n",
      "          55.73478197572927\n",
      "        ]\n",
      "      ]\n",
      "    ]\n",
      "  },\n",
      "  \"links\": [\n",
      "    {\n",
      "      \"rel\": \"root\",\n",
      "      \"href\": \"../catalog.json\",\n",
      "      \"type\": \"application/json\"\n",
      "    },\n",
      "    {\n",
      "      \"rel\": \"parent\",\n",
      "      \"href\": \"../catalog.json\",\n",
      "      \"type\": \"application/json\"\n",
      "    }\n",
      "  ],\n",
      "  \"assets\": {\n",
      "    \"image\": {\n",
      "      \"href\": \"/var/folders/73/z5lbqv_s6l7fcfx464_pn8p80000gn/T/tmp17i4icyl/image.tif\",\n",
      "      \"type\": \"image/tiff; application=geotiff\"\n",
      "    }\n",
      "  },\n",
      "  \"bbox\": [\n",
      "    37.6616853489879,\n",
      "    55.73478197572927,\n",
      "    37.66573047610874,\n",
      "    55.73882710285011\n",
      "  ],\n",
      "  \"stac_extensions\": []\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "with open(item.self_href) as f:\n",
    "    print(f.read())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4119cf42",
   "metadata": {},
   "source": [
    "### Save the Catalog: Absolute Published"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8293f6db",
   "metadata": {},
   "source": [
    "As you can see, all links are saved with relative paths. That’s because we used `catalog_type=CatalogType.SELF_CONTAINED`. If we save an *Absolute Published Catalog*, we’ll see absolute paths.\n",
    "\n",
    "An *Absolute Published Catalog* is a catalog that uses absolute links for everything, both in the links objects and in the asset hrefs.\n",
    "\n",
    "Let's try saving the same catalog with the `CatalogType` as `ABSOLUTE_PUBLISHED`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "9eb88a3a",
   "metadata": {},
   "outputs": [],
   "source": [
    "catalog.save(catalog_type=pystac.CatalogType.ABSOLUTE_PUBLISHED)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ab35e3f",
   "metadata": {},
   "source": [
    "Now the links included in the STAC Item are all absolute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "9e60228c",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "  \"type\": \"Feature\",\n",
      "  \"stac_version\": \"1.0.0\",\n",
      "  \"id\": \"local-image\",\n",
      "  \"properties\": {\n",
      "    \"datetime\": \"2023-10-18T03:10:18.923211Z\"\n",
      "  },\n",
      "  \"geometry\": {\n",
      "    \"type\": \"Polygon\",\n",
      "    \"coordinates\": [\n",
      "      [\n",
      "        [\n",
      "          37.6616853489879,\n",
      "          55.73478197572927\n",
      "        ],\n",
      "        [\n",
      "          37.6616853489879,\n",
      "          55.73882710285011\n",
      "        ],\n",
      "        [\n",
      "          37.66573047610874,\n",
      "          55.73882710285011\n",
      "        ],\n",
      "        [\n",
      "          37.66573047610874,\n",
      "          55.73478197572927\n",
      "        ],\n",
      "        [\n",
      "          37.6616853489879,\n",
      "          55.73478197572927\n",
      "        ]\n",
      "      ]\n",
      "    ]\n",
      "  },\n",
      "  \"links\": [\n",
      "    {\n",
      "      \"rel\": \"root\",\n",
      "      \"href\": \"/var/folders/73/z5lbqv_s6l7fcfx464_pn8p80000gn/T/tmp17i4icyl/stac/catalog.json\",\n",
      "      \"type\": \"application/json\"\n",
      "    },\n",
      "    {\n",
      "      \"rel\": \"parent\",\n",
      "      \"href\": \"/var/folders/73/z5lbqv_s6l7fcfx464_pn8p80000gn/T/tmp17i4icyl/stac/catalog.json\",\n",
      "      \"type\": \"application/json\"\n",
      "    },\n",
      "    {\n",
      "      \"rel\": \"self\",\n",
      "      \"href\": \"/var/folders/73/z5lbqv_s6l7fcfx464_pn8p80000gn/T/tmp17i4icyl/stac/local-image/local-image.json\",\n",
      "      \"type\": \"application/json\"\n",
      "    }\n",
      "  ],\n",
      "  \"assets\": {\n",
      "    \"image\": {\n",
      "      \"href\": \"/var/folders/73/z5lbqv_s6l7fcfx464_pn8p80000gn/T/tmp17i4icyl/image.tif\",\n",
      "      \"type\": \"image/tiff; application=geotiff\"\n",
      "    }\n",
      "  },\n",
      "  \"bbox\": [\n",
      "    37.6616853489879,\n",
      "    55.73478197572927,\n",
      "    37.66573047610874,\n",
      "    55.73882710285011\n",
      "  ],\n",
      "  \"stac_extensions\": []\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "with open(item.get_self_href()) as f:\n",
    "    print(f.read())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "45f0351f",
   "metadata": {},
   "source": [
    "Notice that the asset `href` is absolute in both cases. We can make the asset `href` relative to the STAC Item by using `.make_all_asset_hrefs_relative()`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "e07cf41e",
   "metadata": {},
   "outputs": [],
   "source": [
    "catalog.make_all_asset_hrefs_relative()\n",
    "catalog.save(catalog_type=pystac.CatalogType.SELF_CONTAINED)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "id": "5536e8a2",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      "  \"type\": \"Feature\",\n",
      "  \"stac_version\": \"1.0.0\",\n",
      "  \"id\": \"local-image\",\n",
      "  \"properties\": {\n",
      "    \"datetime\": \"2023-10-18T03:10:18.923211Z\"\n",
      "  },\n",
      "  \"geometry\": {\n",
      "    \"type\": \"Polygon\",\n",
      "    \"coordinates\": [\n",
      "      [\n",
      "        [\n",
      "          37.6616853489879,\n",
      "          55.73478197572927\n",
      "        ],\n",
      "        [\n",
      "          37.6616853489879,\n",
      "          55.73882710285011\n",
      "        ],\n",
      "        [\n",
      "          37.66573047610874,\n",
      "          55.73882710285011\n",
      "        ],\n",
      "        [\n",
      "          37.66573047610874,\n",
      "          55.73478197572927\n",
      "        ],\n",
      "        [\n",
      "          37.6616853489879,\n",
      "          55.73478197572927\n",
      "        ]\n",
      "      ]\n",
      "    ]\n",
      "  },\n",
      "  \"links\": [\n",
      "    {\n",
      "      \"rel\": \"root\",\n",
      "      \"href\": \"../catalog.json\",\n",
      "      \"type\": \"application/json\"\n",
      "    },\n",
      "    {\n",
      "      \"rel\": \"parent\",\n",
      "      \"href\": \"../catalog.json\",\n",
      "      \"type\": \"application/json\"\n",
      "    }\n",
      "  ],\n",
      "  \"assets\": {\n",
      "    \"image\": {\n",
      "      \"href\": \"../../image.tif\",\n",
      "      \"type\": \"image/tiff; application=geotiff\"\n",
      "    }\n",
      "  },\n",
      "  \"bbox\": [\n",
      "    37.6616853489879,\n",
      "    55.73478197572927,\n",
      "    37.66573047610874,\n",
      "    55.73882710285011\n",
      "  ],\n",
      "  \"stac_extensions\": []\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "with open(item.get_self_href()) as f:\n",
    "    print(f.read())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ab5bee7d",
   "metadata": {},
   "source": [
    "There you have it: your very first STAC Catalog. In the [following tutorial](/en/tutorials/3-create-stac-item-with-extension/index.html), you will learn how to add an Item with EO Extensions and a STAC Collection to this STAC Catalog."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bc6b8624",
   "metadata": {},
   "source": [
    "## Cleanup\n",
    "\n",
    "Don't forget to clean up the temporary directory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "id": "0c854cbe",
   "metadata": {},
   "outputs": [],
   "source": [
    "tmp_dir.cleanup()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fce058e6",
   "metadata": {},
   "source": [
    "#### Join the conversation\n",
    "If you have any questions, you’re welcome to ask our community on [Gitter](https://app.gitter.im/#/room/#SpatioTemporal-Asset-Catalog_Lobby)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "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.10.8"
  },
  "vscode": {
   "interpreter": {
    "hash": "b0fa6594d8f4cbf19f97940f81e996739fb7646882a419484c72d19e05852a7e"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}