{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0",
   "metadata": {},
   "source": [
    "# Rich Display of Typed Objects\n",
    "\n",
    "This notebook demonstrates how to use `evo.widgets` to display Evo SDK typed objects\n",
    "with rich HTML formatting in Jupyter notebooks.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1",
   "metadata": {},
   "source": [
    "## Setup\n",
    "\n",
    "First, authenticate and load the widgets extension:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2",
   "metadata": {},
   "outputs": [],
   "source": [
    "from evo.notebooks import ServiceManagerWidget\n",
    "\n",
    "manager = await ServiceManagerWidget.with_auth_code(\n",
    "    client_id=\"your-client-id\",\n",
    "    cache_location=\"./notebook-data\",\n",
    ").login()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load the widgets extension for rich HTML display\n",
    "%load_ext evo.widgets"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4",
   "metadata": {},
   "source": [
    "## How It Works\n",
    "\n",
    "When you run `%load_ext evo.widgets`, the extension registers HTML formatters for\n",
    "Evo SDK typed objects with IPython. This means any object that inherits from `_BaseObject`\n",
    "(such as `PointSet`, `Regular3DGrid`, `TensorGrid`, etc.) will automatically render with\n",
    "rich HTML when displayed in a notebook cell.\n",
    "\n",
    "The formatters use IPython's `for_type_by_name` mechanism, which means:\n",
    "- No hard dependency on `evo-objects` in the widgets package\n",
    "- Formatters are only applied when the relevant types are loaded\n",
    "- Works with all current and future typed objects\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5",
   "metadata": {},
   "source": [
    "## Loading Objects from Path\n",
    "\n",
    "You can load existing objects using `object_from_path`. When displayed in a notebook,\n",
    "objects automatically render with a styled HTML representation including:\n",
    "- Object name and metadata\n",
    "- Links to Portal and Viewer\n",
    "- Bounding box information\n",
    "- Coordinate reference system\n",
    "- Attribute summaries\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6",
   "metadata": {},
   "outputs": [],
   "source": [
    "from evo.objects.typed import object_from_path\n",
    "\n",
    "# Load a Regular 3D Grid - displays with rich HTML formatting\n",
    "grid = await object_from_path(manager, \"/Test Grid\")\n",
    "grid"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7",
   "metadata": {},
   "source": [
    "## Loading Different Object Types\n",
    "\n",
    "The widgets extension works with all typed objects:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load a PointSet - same rich formatting\n",
    "pointset = await object_from_path(manager, \"/Test PointSet\")\n",
    "pointset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load a Tensor Grid\n",
    "tensor_grid = await object_from_path(manager, \"/Test Tensor Grid\")\n",
    "tensor_grid"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10",
   "metadata": {},
   "source": [
    "## Viewing Object Attributes\n",
    "\n",
    "Attributes collections also render with rich formatting:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "11",
   "metadata": {},
   "outputs": [],
   "source": [
    "# View cell attributes for a grid\n",
    "grid.attributes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "12",
   "metadata": {},
   "outputs": [],
   "source": [
    "# View vertex attributes\n",
    "grid.vertex_attributes"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "13",
   "metadata": {},
   "source": [
    "## Accessing Object Properties\n",
    "\n",
    "You can still access all properties programmatically:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "14",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f\"Name: {grid.name}\")\n",
    "print(f\"Schema: {grid.metadata.schema}\")\n",
    "print(f\"Object ID: {grid.metadata.id}\")\n",
    "print(f\"Origin: {grid.origin}\")\n",
    "print(f\"Size: {grid.size}\")\n",
    "print(f\"Bounding Box: {grid.bounding_box}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15",
   "metadata": {},
   "source": [
    "## Generating Portal and Viewer URLs\n",
    "\n",
    "Use the URL helpers to generate links for viewing objects:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "16",
   "metadata": {},
   "outputs": [],
   "source": [
    "from evo.widgets import get_viewer_url_for_objects\n",
    "\n",
    "# Generate a URL to view multiple objects together\n",
    "url = get_viewer_url_for_objects(manager, [grid, pointset])\n",
    "print(f\"Viewer URL: {url}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "17",
   "metadata": {},
   "source": [
    "## Working with DataFrames\n",
    "\n",
    "Get object data as pandas DataFrames for analysis:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "18",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get cell data as DataFrame\n",
    "cell_df = await grid.to_dataframe()\n",
    "cell_df.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "19",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get vertex data\n",
    "vertex_df = await grid.vertices.to_dataframe()\n",
    "vertex_df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "20",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "The `evo.widgets` extension provides:\n",
    "\n",
    "1. **Rich HTML rendering** - Automatic pretty-printing of typed objects\n",
    "2. **Portal/Viewer links** - One-click access to view objects in the web UI\n",
    "3. **Attribute tables** - Formatted summaries of object attributes\n",
    "4. **URL helpers** - Generate viewer URLs for multiple objects\n",
    "\n",
    "To use it, simply:\n",
    "```python\n",
    "%load_ext evo.widgets\n",
    "```\n",
    "\n",
    "All Evo SDK typed objects will then automatically render with rich formatting when displayed.\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
