examples/02_adding_objects_to_plot.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Adding objects to plot\n",
    "\n",
    "In this example we will draw a simple 3D primitive, add it to the plot,\n",
    "and display the result.\n",
    "\n",
    "To draw the triangle we will use the `mesh()` method from the `k3d` module.\n",
    "This method creates a `Mesh` object, which can be added to a K3D `Plot`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import k3d\n",
    "plot = k3d.plot()\n",
    "\n",
    "\n",
    "vertices = [[0, 0, 0], [0, 0, 1], [1, 0, 0]]\n",
    "indices = [[0, 1, 2]]\n",
    "\n",
    "mesh = k3d.mesh(vertices, indices)\n",
    "\n",
    "plot += mesh\n",
    "\n",
    "plot.display()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Expected result:\n",
    "![An isosceles triangle in the y=0 plane](assets/02_one_triangle.png \"The simplest mesh: a single triangle\")\n",
    "\n",
    "The arguments we passed to the `mesh()` function are a vertex array (a `list` or NumPy's `ndarray` is OK) which is composed of $(x, y, z)$ coordinates and an array of index triplets (`int`s). Each triplet refers to the vertex array, defining one triangle.\n",
    "\n",
    "We can of course add objects directly to the plot, without creating variables:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot += k3d.mesh([0, 1, 1, \n",
    "                 1, 1, 0, \n",
    "                 1, 1, 1,\n",
    "                 \n",
    "                 1, 1, 1,\n",
    "                 1, 2, 2,\n",
    "                 2, 1, 1], [0, 1, 2, 3, 4, 5], color=0x00ff00)\n",
    "\n",
    "plot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Expected result:\n",
    "![One blue and two green triangles](assets/02_two_triangles.png \"Three triangles, two Mesh objects\")\n",
    "\n",
    "This is a plot of two meshes. Please note -- in the second case we didn't nest the triplets - the numbers run continuously in a flat list. We also used an optional argument, `color` to specify the color of the second object. K3D objects have many attributes, which we can find out about from the docstrings and from other examples, dedicated to the specific object type.\n",
    "\n",
    "Back to the main topic. The `plot` keeps track of the objects that it contains:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "len(plot.objects)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have 2 displays of the plot in the notebook, associated with 2 different cell outputs.\n",
    "However, they are the same plot - you should see the same scene (3 triangles) on both of them.\n",
    "Each view of the plot can be adjusted separately using the mouse.\n",
    "\n",
    "When the plot becomes too cluttered with objects, we may want to remove some of them.\n",
    "This is easily done with the `-=` operator. This is the place, where having named our \n",
    "objects beforehand comes in handy:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot -= mesh\n",
    "plot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "Expected result:\n",
    "![Just the second mesh](assets/02_only_second.png \"We can remove the objects in any order\")\n",
    "\n",
    "Having variables is also convenient when we want to modify the objects already shown.\n",
    "This will be demonstrated in another example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}