tutorials/Ex001 Simple Block.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Prev](Ex000%20Start%20Here.ipynb) | [Top](Ex000%20Start%20Here.ipynb) | Next"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Ex001 Simple Block"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***Note:*** If live coding and experimentation are desired, it is required to hit _Shift+Enter_ on each of the code cells below to execute them."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Import the CadQuery library"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cadquery as cq"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`cadquery` is the core library that is used while scripting models, and that other libraries in the community are built upon. It is not required that you import it with the \"cq\" alias, but it helps to shorten lines of code. Use of the alias is personal preference, but it is seen quite a bit in scripts created by the community."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Import the jupyter-cadquery Display Method"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from jupyter_cadquery.cadquery import show as show_object"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following import is required because these tutorials use the [jupyter-cadquery](https://github.com/bernhard-42/jupyter-cadquery) extension for JupyterLab. When using [CQ-editor](https://github.com/CadQuery/CQ-editor) or running a CadQuery script from the command line, this import will not be needed. If you continue to use jupyter-cadquery, have a look at the [`show` method](https://github.com/bernhard-42/jupyter-cadquery/blob/master/jupyter_cadquery/cadquery/cad_objects.py#L174), which allows you to customize various aspects of how the model is displayed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Set Up Model Parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "length = 80.0       # Length of the block\n",
    "height = 60.0       # Height of the block\n",
    "thickness = 10.0    # Thickness of the block"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is a best practice to avoid hardcoding model parameters that can change. Variables can be set for the parameters so that they can be used throughout your script and still changed in one place easily. Units can be added to parameters using external libraries such as [pint](https://pint.readthedocs.io/en/latest/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Create a Simple Box Model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "result = cq.Workplane(\"XY\").box(length, height, thickness)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this line of code, `cq.Workplane(\"XY\")` uses the X and Y axes to define a workplane, meaning that the positive Z direction is \"up\", and the negative Z direction is \"down\". If you hold your hand open with the palm facing up, your thumb will point in the positive X direction, your fingers in the positive Y direction, and up from your palm will be the positive Z direction. Other [named views](https://cadquery.readthedocs.io/en/latest/classreference.html#cadquery.Workplane) can be passed to `Workplane` as well, such as \"front\" and \"XZ\". A workplane is like a virtual surface on which you can place geometry that you use while building your model. In CadQuery, creating and manipulating workplanes is a task that you will do quite a lot, and will be covered in more depth in later tutorials."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once the workplane has been created, `box(length, height, thickness)` is called to create a CQ box primitive on the workplane. Notice that the `box` method call uses the parameter variables that were created above, instead of hardcoded values. The box will be centered around the origin by default, but this behavior can be overridden by passing the `centered` parameter. Additional information about the box method can be found [here](https://cadquery.readthedocs.io/en/latest/classreference.html#cadquery.Workplane.box). CadQuery also has other primitives, including [sphere](https://cadquery.readthedocs.io/en/latest/classreference.html#cadquery.Workplane.sphere) and [wedge](https://cadquery.readthedocs.io/en/latest/classreference.html#cadquery.Workplane.wedge) which are covered in the documentation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One other thing to note about this line of code is that the box method is tacked on directly after the `Workplane` call. This chaining is enabled by the fact that most high level CadQuery methods return CQ objects. This leads to very compact code, although chaining too many calls together can make your code harder to read. Oftentimes you will want to break chains down into logical operations that build on one another. Some CadQuery methods will alter the CQ object in place rather than returning a new object, so it is best to consult the documentation for a method to ensure that you are using it properly."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Display the Box Model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "show_object(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`show_object` will handle the task of displaying the model differently based on which exection environment you are using (Jupyter-CadQuery, CQ-editor, command line, etc). If you are planning to run your script from the command line, it may be more appropriate to instead use one of the export methods to save your model in a format that you can open in an external application. More information on exporting CQ objects can be found in [here](https://cadquery.readthedocs.io/en/latest/apireference.html#file-management-and-export)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. Complete Script"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cadquery as cq\n",
    "from jupyter_cadquery.cadquery import show as show_object\n",
    "\n",
    "# These can be modified rather than hardcoding values for each dimension.\n",
    "length = 80.0       # Length of the block\n",
    "height = 60.0       # Height of the block\n",
    "thickness = 10.0    # Thickness of the block\n",
    "\n",
    "# Create a 3D block based on the dimension variables above.\n",
    "# 1.  Establishes a workplane that an object can be built on.\n",
    "# 1a. Uses the X and Y origins to define the workplane, meaning that the\n",
    "# positive Z direction is \"up\", and the negative Z direction is \"down\".\n",
    "result = cq.Workplane(\"XY\").box(length, height, thickness)\n",
    "\n",
    "# Display the model\n",
    "show_object(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 7. Next Steps"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can now move onto the [next section](). Complete documentation for a deeper exploration of these topics is available [here](https://cadquery.readthedocs.io/en/latest/index.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[Top](Ex000%20Start%20Here.ipynb) | Next"
   ]
  }
 ],
 "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}