304 lines
10 KiB
ReStructuredText
304 lines
10 KiB
ReStructuredText
|
|
.. module:: cadquery
|
|
|
|
.. _quickstart:
|
|
|
|
***********************
|
|
CadQuery QuickStart
|
|
***********************
|
|
|
|
Want a quick glimpse of Parametric Parts ModelScripts? You're at the right place!
|
|
This quickstart will demonstrate the basics of ModelScripts using a simple example
|
|
|
|
Prerequisites
|
|
=============
|
|
|
|
**WebGL Capable Browser**
|
|
|
|
CadQuery renders models in your browser using WebGL-- which is supported by most browsers *except for IE*
|
|
You can follow along without IE, but you will not be able to see the model dynamically rendered
|
|
|
|
|
|
What we'll accomplish
|
|
=====================
|
|
|
|
Our finished object will look like this:
|
|
|
|
.. image:: quickstart.png
|
|
|
|
|
|
**We would like our block to have these features:**
|
|
|
|
1. It should be sized to hold a single 608 ( 'skate' ) bearing, in the center of the block.
|
|
2. It should have counter sunk holes for M2 socket head cap screws at the corners
|
|
3. The length and width of the block should be configurable by the user to any reasonable size.
|
|
|
|
A human would describe this as:
|
|
|
|
"A rectangular block 80mm x 60mm x 30mm , with countersunk holes for M2 socket head cap screws
|
|
at the corners, and a circular pocket 22mm in diameter in the middle for a bearing"
|
|
|
|
Human descriptions are very elegant, right?
|
|
Hopefully our finished script will not be too much more complex than this human-oriented description.
|
|
|
|
Let's see how we do.
|
|
|
|
Start a new Model
|
|
==================================
|
|
|
|
CadQuery comes with an online, interactive default model as a starting point. Lets open up that tool
|
|
`here <http://www.parametricparts.com/parts/create>`_
|
|
|
|
You should see the dynamic model creator page, which will display a sample model:
|
|
|
|
.. image:: _static/quickstart-1.png
|
|
|
|
Take a minute to play with this model. Here are a few things to try:
|
|
|
|
1. Use the mouse to rotate the block
|
|
2. Play with the view controls under the image
|
|
3. change the length ( the only available parameter),
|
|
and use the preview button to re-display the updated model
|
|
4. Change the preset value to `short`
|
|
5. Edit the model script itself. Change the hard-coded width and thickness values and click 'update script'
|
|
to re-display the model.
|
|
|
|
At this point, you should have some idea how to interact with the sample model, so lets get to work on the project.
|
|
|
|
Modify MetaData and Parameters
|
|
==============================
|
|
|
|
Each model has metadata that describes the model's properties. The default Unit of Measure (UOM) will work:
|
|
|
|
.. code-block:: python
|
|
:linenos:
|
|
:emphasize-lines: 1
|
|
|
|
UOM = "mm"
|
|
|
|
|
|
Next, lets set up the parameters. Parameters are `placeholders` that users can modify separately from the script itself.
|
|
The default model has a single parameter, ``length``. Lets add a ``height`` parameter too
|
|
|
|
.. code-block:: python
|
|
:linenos:
|
|
:emphasize-lines: 4
|
|
|
|
UOM = "mm"
|
|
|
|
length = FloatParam(min=30.0,max=200.0,presets={'default':80.0,'short':30.0},desc="Length of the block")
|
|
height = FloatParam(min=30.0,max=200.0,presets={'default':60.0,'short':30.0},desc="Height of the block")
|
|
thickness = 10.0
|
|
|
|
def build():
|
|
return Workplane("XY").box(length.value,height.value,thickness)
|
|
|
|
We've set the minimum values to 30 mm, since that's about as small as it could be while having room for a bearing 22mm
|
|
in diameter. We've also set the default values to be those we'd like to start with: 80mm for the length and 60mm for the
|
|
height.
|
|
|
|
Now, modify the build script to use your width value to make the block by changing ``height`` to
|
|
``height.value``
|
|
|
|
.. code-block:: python
|
|
:linenos:
|
|
:emphasize-lines: 3
|
|
|
|
...
|
|
def build():
|
|
return Workplane("XY").box(length.value,height.value,thickness)
|
|
|
|
The value property always returns the ``user-adjusted`` value of the parameter. That's good enough for now.
|
|
Click "Save Changes" and you should see your 80x60x10mm base plate, like this:
|
|
|
|
.. image:: _static/quickstart-2.png
|
|
|
|
If you'd like to come back to this model later, the url bar links to the newly created part.
|
|
|
|
Now lets move on and make this boring plate into a pillow block.
|
|
|
|
|
|
Add the Holes
|
|
================
|
|
|
|
Our pillow block needs to have a 22mm diameter hole in the center of this block to hold the bearing.
|
|
|
|
This modification will do the trick:
|
|
|
|
.. code-block:: python
|
|
:linenos:
|
|
:emphasize-lines: 3
|
|
|
|
...
|
|
def build():
|
|
return Workplane("XY").box(length.value,height.value,thickness).faces(">Z").workplane().hole(22.0)
|
|
|
|
Rebuild your model by clicking "Save Model" at the bottom. Your block should look like this:
|
|
|
|
.. image:: _static/quickstart-3.png
|
|
|
|
|
|
The code is pretty compact, and works like this:
|
|
* :py:meth:`Workplane.faces` selects the top-most face in the Z direction, and
|
|
* :py:meth:`Workplane.workplane` begins a new workplane located on this face
|
|
* :py:meth:`Workplane.hole` drills a hole through the part 22mm in diamter
|
|
|
|
.. note::
|
|
|
|
Don't worry about the CadQuery syntax now.. you can learn all about it in the :ref:`apireference` later.
|
|
|
|
More Holes
|
|
============
|
|
|
|
Ok, that hole was not too hard, but what about the counter-bored holes in the corners?
|
|
|
|
An M2 Socket head cap screw has these dimensions:
|
|
|
|
* **Head Diameter** : 3.8 mm
|
|
* **Head height** : 2.0 mm
|
|
* **Clearance Hole** : 2.4 mm
|
|
* **CounterBore diameter** : 4.4 mm
|
|
|
|
The centers of these holes should be 4mm from the edges of the block. And,
|
|
we want the block to work correctly even when the block is re-sized by the user.
|
|
|
|
**Don't tell me** we'll have to repeat the steps above 8 times to get counter-bored holes?
|
|
|
|
Good news!-- we can get the job done with just two lines of code. Here's the code we need:
|
|
|
|
.. code-block:: python
|
|
:linenos:
|
|
:emphasize-lines: 4-5
|
|
|
|
...
|
|
def build():
|
|
return Workplane("XY").box(length.value,height.value,thickness).faces(">Z").workplane().hole(22.0) \
|
|
.faces(">Z").workplane() \
|
|
.rect(length.value-8.0,height.value-8.0,forConstruction=True) \
|
|
.vertices().cboreHole(2.4,4.4,2.1)
|
|
|
|
You should see something like this:
|
|
|
|
.. image:: _static/quickstart-4.png
|
|
|
|
Lets Break that down a bit
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
**Line 4** selects the top-most face of the block, and creates a workplane on the top that face, which we'll use to
|
|
define the centers of the holes in the corners:
|
|
|
|
.. code-block:: python
|
|
:linenos:
|
|
:emphasize-lines: 4
|
|
|
|
...
|
|
def build():
|
|
return Workplane("XY").box(length.value,height.value,thickness).faces(">Z").workplane().hole(22.0) \
|
|
.faces(">Z").workplane() \
|
|
.rect(length.value-8.0,width.value-8.0,forConstruction=True) \
|
|
.vertices().cboreHole(2.4,4.4,2.1)
|
|
|
|
|
|
**Line 5** draws a rectangle 8mm smaller than the overall length and width of the block,which we will use to
|
|
locate the corner holes:
|
|
|
|
.. code-block:: python
|
|
:linenos:
|
|
:emphasize-lines: 5
|
|
|
|
...
|
|
def build():
|
|
return Workplane("XY").box(length.value,height.value,thickness).faces(">Z").workplane().hole(22.0) \
|
|
.faces(">Z").workplane() \
|
|
.rect(length.value-8.0,width.value-8.0,forConstruction=True) \
|
|
.vertices().cboreHole(2.4,4.4,2.1)
|
|
|
|
There are a couple of things to note about this line:
|
|
|
|
1. The :py:meth:`Workplane.rect` function draws a rectangle. **forConstruction=True**
|
|
tells CadQuery that this rectangle will not form a part of the solid,
|
|
but we are just using it to help define some other geometry.
|
|
2. The center point of a workplane on a face is always at the center of the face, which works well here
|
|
3. Unless you specifiy otherwise, a rectangle is drawn with its center on the current workplane center-- in
|
|
this case, the center of the top face of the block. So this rectangle will be centered on the face
|
|
|
|
|
|
**Line 6** selects the corners of the rectangle, and makes the holes:
|
|
|
|
.. code-block:: python
|
|
:linenos:
|
|
:emphasize-lines: 6
|
|
|
|
...
|
|
def build():
|
|
return Workplane("XY").box(length.value,height.value,thickness).faces(">Z").workplane().hole(22.0) \
|
|
.faces(">Z").workplane() \
|
|
.rect(length.value-8.0,width.value-8.0,forConstruction=True) \
|
|
.vertices().cboreHole(2.4,4.4,2.1)
|
|
|
|
Notes about this line:
|
|
|
|
1. The :py:meth:`CQ.vertices` function selects the corners of the rectangle
|
|
2. The :py:meth:`Workplane.cboreHole` function is a handy CadQuery function that makes a counterbored hole
|
|
3. ``cboreHole``, like most other CadQuery functions, operate on the values on the stack. In this case, since
|
|
selected the four vertices before calling the function, the function operates on each of the four points--
|
|
which results in a counterbore hole at the corners.
|
|
|
|
Presets
|
|
===========
|
|
|
|
Almost done. This model is pretty easy to configure, but we can make it even easier by providing users with a few
|
|
'out of the box' options to choose from. Lets provide two preset options:
|
|
|
|
* **Small** : 30 mm x 40mm
|
|
* **Square-Medium** : 50 mm x 50mm
|
|
|
|
We can do that using the preset dictionaries in the parameter definition:
|
|
|
|
.. code-block:: python
|
|
:linenos:
|
|
:emphasize-lines: 2-3
|
|
|
|
...
|
|
length = FloatParam(min=10.0,max=500.0,presets={'default':100.0,'small':30.0,'square-medium':50},desc="Length of the box")
|
|
height = FloatParam(min=30.0,max=200.0,presets={'default':60.0,'small':40.0,'square-medium':50},desc="Height of the block")
|
|
|
|
Now save the model and have a look at the preset DDLB-- you'll see that you can easily switch between these
|
|
configurations:
|
|
|
|
.. image:: _static/quickstart-5.png
|
|
|
|
|
|
Done!
|
|
============
|
|
|
|
And... We're done! Congratulations, you just made a parametric, 3d model with 15 lines of code.Users can use this
|
|
model to generate pillow blocks in any size they would like
|
|
|
|
For completeness, Here's a copy of the finished model:
|
|
|
|
.. code-block:: python
|
|
:linenos:
|
|
|
|
UOM = "mm"
|
|
|
|
length = FloatParam(min=10.0,max=500.0,presets={'default':100.0,'small':30.0,'square-medium':50},desc="Length of the box")
|
|
height = FloatParam(min=30.0,max=200.0,presets={'default':60.0,'small':40.0,'square-medium':50},desc="Height of the block")
|
|
|
|
width = 40.0
|
|
thickness = 10.0
|
|
|
|
def build():
|
|
return Workplane("XY").box(length.value,height.value,thickness).faces(">Z").workplane().hole(22.0) \
|
|
.faces(">Z").workplane() \
|
|
.rect(length.value-8.0,height.value-8.0,forConstruction=True) \
|
|
.vertices().cboreHole(2.4,4.4,2.1)
|
|
|
|
|
|
Want to learn more?
|
|
====================
|
|
|
|
* The :ref:`examples` contains lots of examples demonstrating cadquery features
|
|
* The :ref:`apireference` is a good overview of language features grouped by function
|
|
* The :ref:`classreference` is the hard-core listing of all functions available. |