{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial 1a: Optiland for Beginners\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Last verified against Optiland v0.6.1.*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This tutorial describes the basics of Optiland. In particular, the following topics are covered:\n",
    "\n",
    "- Basic lens entry\n",
    "- Material definition and selection\n",
    "- Aperture, field and wavelength selection\n",
    "- Checking a system for common mistakes\n",
    "- Drawing a lens in 2D and 3D"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A complete lens, first\n",
    "\n",
    "Below is a full, working optical system: a singlet with a 25 mm entrance pupil, one on-axis field, and one wavelength. Run it and you get a ray-traced layout. Everything after this cell explains what each line does — but the whole program is already here, and it is not long."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-24T09:48:40.131691Z",
     "iopub.status.busy": "2026-03-24T09:48:40.131535Z",
     "iopub.status.idle": "2026-03-24T09:48:43.052115Z",
     "shell.execute_reply": "2026-03-24T09:48:43.051665Z"
    }
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "from optiland import optic"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(<Figure size 1000x400 with 1 Axes>, <Axes: xlabel='Z [mm]', ylabel='Y [mm]'>)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 1000x400 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "singlet = optic.Optic()\n",
    "\n",
    "# define surfaces\n",
    "singlet.surfaces.add(index=0, radius=np.inf, thickness=np.inf)\n",
    "singlet.surfaces.add(index=1, radius=20, thickness=7, is_stop=True, material=\"N-SF11\")\n",
    "singlet.surfaces.add(index=2, radius=np.inf, thickness=18)\n",
    "singlet.surfaces.add(index=3)\n",
    "\n",
    "# define aperture\n",
    "singlet.set_aperture(aperture_type=\"EPD\", value=25)\n",
    "\n",
    "# define fields\n",
    "singlet.fields.set_type(field_type=\"angle\")\n",
    "singlet.fields.add(y=0)\n",
    "\n",
    "# define wavelengths\n",
    "singlet.wavelengths.add(value=0.5, is_primary=True)\n",
    "\n",
    "# draw it\n",
    "singlet.draw(num_rays=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> **Note:**  \n",
    "The `draw()` method returns the matplotlib figure and axes.  \n",
    "When running Optiland in a script, you must explicitly call `plt.show()` or `fig.show()` to display the plot.  \n",
    "\n",
    "In Jupyter notebooks, figures are displayed automatically."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That is the entire program. The rest of this tutorial takes it apart line by line.\n",
    "\n",
    "> **One convention to internalize before you read further:** a surface's `thickness` and `material` describe the space that *follows* it, not the surface itself. So `surfaces.add(index=1, thickness=7, material=\"N-SF11\")` means *7 mm of N-SF11 glass between surface 1 and surface 2*.\n",
    "\n",
    "<figure style=\"text-align: left;\">\n",
    "  <img src=\"../images/after_rule.svg\" alt=\"A surface's thickness and material describe the space after it\" style=\"width: 700px; max-width: 100%;\">\n",
    "</figure>\n",
    "\n",
    "The full set of conventions — sign conventions, units, the object/image surface rule, and stop vs. aperture vs. pupil — lives on the [Conventions](../conventions.rst) page. It is worth the five minutes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "source": [
    "## Defining a lens, in detail:\n",
    "\n",
    "### Create the optic:\n",
    "\n",
    "In Optiland, lenses are instances of the \"Optic\" class. The process for defining a lens starts with creating an empty \"Optic\" object as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-24T10:11:57.423198Z",
     "iopub.status.busy": "2026-03-24T10:11:57.423024Z",
     "iopub.status.idle": "2026-03-24T10:11:57.425574Z",
     "shell.execute_reply": "2026-03-24T10:11:57.425069Z"
    }
   },
   "outputs": [],
   "source": [
    "lens = optic.Optic()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Add the object surface:\n",
    "\n",
    "We now want to populate the lens object with surfaces. Let's first add the object surface, which will be at infinity and will have a radius of infinity, i.e. it is a plane. We add the surface by calling the \"add_surface\" method. We must specify the index as 0 to indicate this is the first surface."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-24T10:11:57.427287Z",
     "iopub.status.busy": "2026-03-24T10:11:57.427113Z",
     "iopub.status.idle": "2026-03-24T10:11:57.430092Z",
     "shell.execute_reply": "2026-03-24T10:11:57.429706Z"
    }
   },
   "outputs": [],
   "source": [
    "lens.surfaces.add(index=0, radius=np.inf, thickness=np.inf)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Add a lens:\n",
    "\n",
    "Let's now add a singlet lens:\n",
    "\n",
    "- Material: N-SF11\n",
    "- Thickness: 7 mm\n",
    "- Radius side 1: 20 mm\n",
    "- Radius side 2: infinity\n",
    "- Stop surface: 1\n",
    "\n",
    "Optiland defines lenses one surface at a time, so each side of the lens is a separate surface — indices 1 and 2 here, following the object plane at index 0.\n",
    "\n",
    "Because `thickness` and `material` describe the space *after* a surface (the \"after\" rule above), surface 1 carries `thickness=7, material=\"N-SF11\"` — the glass — and surface 2 carries `thickness=18`, the air gap to the image plane. Surface 2 needs no material: air is the default. See [Conventions](../conventions.rst) for the sign conventions and units that go with this.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-24T10:11:57.431847Z",
     "iopub.status.busy": "2026-03-24T10:11:57.431661Z",
     "iopub.status.idle": "2026-03-24T10:11:57.442045Z",
     "shell.execute_reply": "2026-03-24T10:11:57.441550Z"
    }
   },
   "outputs": [],
   "source": [
    "lens.surfaces.add(index=1, thickness=7, radius=20, is_stop=True, material=\"N-SF11\")\n",
    "lens.surfaces.add(index=2, radius=np.inf, thickness=18)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Add image plane:\n",
    "\n",
    "Lastly, let's add the image plane. By default, the radius is infinity, so we can exclude it. We also can omit thickness, as there are no surfaces beyond the image. We need only to define the index, which is 3."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-24T10:11:57.443770Z",
     "iopub.status.busy": "2026-03-24T10:11:57.443592Z",
     "iopub.status.idle": "2026-03-24T10:11:57.446824Z",
     "shell.execute_reply": "2026-03-24T10:11:57.446476Z"
    }
   },
   "outputs": [],
   "source": [
    "lens.surfaces.add(index=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Define aperture:\n",
    "\n",
    "Now, we can define the aperture of the system. Let's choose entrance pupil diameter (EPD) as the aperture type with a value of 25 mm.\n",
    "\n",
    "The options for aperture type are:\n",
    "\n",
    "- 'EPD' - entrance pupil diameter\n",
    "- 'imageFNO' - image-space F-number\n",
    "- 'objectNA' - object-space numerical aperture\n",
    "- 'float_by_stop_size' - the aperture size _floats_ with the size of the stop _diameter_, which is defined by the `value` argument."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-24T10:11:57.449126Z",
     "iopub.status.busy": "2026-03-24T10:11:57.448555Z",
     "iopub.status.idle": "2026-03-24T10:11:57.451582Z",
     "shell.execute_reply": "2026-03-24T10:11:57.451186Z"
    }
   },
   "outputs": [],
   "source": [
    "lens.set_aperture(aperture_type=\"EPD\", value=25)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Define fields:\n",
    "\n",
    "Let's add the fields of the lens. We'll keep it simple and add a single field of type \"angle\" with a value of 0.\n",
    "\n",
    "The options for field types are:\n",
    "\n",
    "- 'angle' - the angle of the field in object space\n",
    "- 'object_height' - the height of the object\n",
    "- 'paraxial_image_height' - the image height of a paraxial chief ray\n",
    "- 'real_image_height' - the image height of a real chief ray"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-24T10:11:57.453319Z",
     "iopub.status.busy": "2026-03-24T10:11:57.453147Z",
     "iopub.status.idle": "2026-03-24T10:11:57.455516Z",
     "shell.execute_reply": "2026-03-24T10:11:57.455154Z"
    }
   },
   "outputs": [],
   "source": [
    "lens.fields.set_type(field_type=\"angle\")\n",
    "lens.fields.add(y=0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Define wavelengths:\n",
    "\n",
    "Lastly, let's define the wavelengths of the system. We define a single wavelength at 0.5 µm. Similar to fields, wavelengths can be assigned a weight to emphasize specific spectral regions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-24T10:11:57.457129Z",
     "iopub.status.busy": "2026-03-24T10:11:57.456963Z",
     "iopub.status.idle": "2026-03-24T10:11:57.459690Z",
     "shell.execute_reply": "2026-03-24T10:11:57.459235Z"
    }
   },
   "outputs": [],
   "source": [
    "lens.wavelengths.add(value=0.5, is_primary=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Sanity-check the lens:\n",
    "\n",
    "Before viewing or tracing rays through the lens, it is good practice to run `check_system`. It inspects the `Optic` for the mistakes newcomers hit most often (a missing wavelength, an undefined aperture, a stop that was never marked, ...) and reports each one with a runnable fix. `report.ok` is `True` once there are no errors left."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<p><strong>DiagnosticReport:</strong> no issues found.</p>"
      ],
      "text/plain": [
       "DiagnosticReport(errors=0, warnings=0)"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from optiland.diagnostics import check_system\n",
    "\n",
    "report = check_system(lens)\n",
    "report"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### View the lens:\n",
    "\n",
    "Let's view the lens in 2D. We can do this by calling the `draw` method.\n",
    "\n",
    "Note that you can also pass a `projection` argument, allowing you to plot in the `\"YZ\"` plane (default), `\"XZ\"` plane, or `\"XY\"` plane.\n",
    "\n",
    "The 2D visualization is now interactive! You can hover over surfaces, lenses, and ray bundles to get more information. You can also customize the look and feel of the plots using themes. See the gallery for an example of how to use themes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-24T10:11:57.461595Z",
     "iopub.status.busy": "2026-03-24T10:11:57.461379Z",
     "iopub.status.idle": "2026-03-24T10:11:57.534768Z",
     "shell.execute_reply": "2026-03-24T10:11:57.534269Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(<Figure size 1000x400 with 1 Axes>, <Axes: xlabel='Z [mm]', ylabel='Y [mm]'>)"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 1000x400 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "lens.draw(num_rays=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": [
     "nbsphinx-toctree"
    ]
   },
   "source": [
    "Finally, we view the lens in 3D using the \"draw3D\" function. Note that this opens a new window."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-24T10:11:57.536757Z",
     "iopub.status.busy": "2026-03-24T10:11:57.536579Z",
     "iopub.status.idle": "2026-03-24T10:11:59.921302Z",
     "shell.execute_reply": "2026-03-24T10:11:59.920406Z"
    }
   },
   "outputs": [],
   "source": [
    "lens.draw3D()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The 3D view opens in a separate VTK window rather than inline, so here is what it looks like:\n",
    "<figure style=\"text-align: left;\">\n",
    "  <img src=\"../images/singlet.png\" alt=\"Singlet\" style=\"width: 500px;\">\n",
    "</figure>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Where to go next\n",
    "\n",
    "You can now build an optical system from scratch, define its aperture, fields and wavelengths, check it for common mistakes, and view it in 2D and 3D. That is enough to enter any sequential system Optiland supports.\n",
    "\n",
    "Next steps, in order of usefulness:\n",
    "\n",
    "- **[Tutorial 1b — Lens Properties and Prescription](Tutorial_1b_Lens_Properties_and_Prescription.ipynb)** — read the first-order properties (EFL, f/#, pupils) back out of a system.\n",
    "- **[Tutorial 1e — Design a Doublet End to End](Tutorial_1e_Design_a_Doublet_End_to_End.ipynb)** — one design carried from requirements through analysis, optimization and tolerancing.\n",
    "- **[Conventions](../conventions.rst)** — the model behind every tutorial, in one page.\n",
    "- **[How do I ...?](../how_do_i.rst)** — a task-shaped index: find your question, get the notebook that answers it."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "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.13.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
