From 9f1ef61e4df9b753dca17ce34a317b9e1c71b045 Mon Sep 17 00:00:00 2001 From: Peter Boin Date: Fri, 20 Jul 2018 22:47:31 +1000 Subject: [PATCH 1/3] converted md to rst --- README.md => README.rst | 263 ++++++++++++++++++++++------------------ setup.py | 2 +- 2 files changed, 146 insertions(+), 119 deletions(-) rename README.md => README.rst (51%) diff --git a/README.md b/README.rst similarity index 51% rename from README.md rename to README.rst index 47249fc..1fd4b32 100644 --- a/README.md +++ b/README.rst @@ -1,15 +1,32 @@ -

- -

+.. image:: http://dcowden.github.io/cadquery/_static/cadquery_logo_dark.svg + :width: 100 + :align: center + What is a CadQuery? ======================================== -[![Travis Build Status](https://travis-ci.org/dcowden/cadquery.svg?branch=master)](https://travis-ci.org/dcowden/cadquery?branch=master) -[![Build status](https://ci.appveyor.com/api/projects/status/c7u4yjl8xxlokrw0/branch/master?svg=true)](https://ci.appveyor.com/project/jmwright/cadquery/branch/master) -[![Coverage Status](https://coveralls.io/repos/github/dcowden/cadquery/badge.svg?branch=master)](https://coveralls.io/github/dcowden/cadquery?branch=master) -[![GitHub version](https://d25lcipzij17d.cloudfront.net/badge.svg?id=gh&type=6&v=1.2.0&x2=0)](https://github.com/dcowden/cadquery/releases/tag/v1.2.0) -[![License](https://img.shields.io/badge/license-Apache2-blue.svg)](https://github.com/dcowden/cadquery/blob/master/LICENSE) +|TRAVIS| |APPVEYOR| |COVERALLS| |VERSION| |LICENSE| + +.. |TRAVIS| image:: https://travis-ci.org/dcowden/cadquery.svg?branch=master + :alt: Travis Build Status + :target: https://travis-ci.org/dcowden/cadquery?branch=master + +.. |APPVEYOR| image:: https://ci.appveyor.com/api/projects/status/c7u4yjl8xxlokrw0/branch/master?svg=true + :alt: Build status + :target: https://ci.appveyor.com/project/jmwright/cadquery/branch/master + +.. |COVERALLS| image:: https://coveralls.io/repos/github/dcowden/cadquery/badge.svg?branch=master + :alt: Coverage Status + :target: https://coveralls.io/github/dcowden/cadquery?branch=master + +.. |VERSION| image:: https://d25lcipzij17d.cloudfront.net/badge.svg?id=gh&type=6&v=1.2.0&x2=0 + :alt: GitHub version + :target: https://github.com/dcowden/cadquery/releases/tag/v1.2.0 + +.. |LICENSE| image:: https://img.shields.io/badge/license-Apache2-blue.svg + :alt: License + :target: https://github.com/dcowden/cadquery/blob/master/LICENSE CadQuery is an intuitive, easy-to-use python based language for building parametric 3D CAD models. CadQuery is for 3D CAD what jQuery is for javascript. Imagine selecting Faces of a 3d object the same way you select DOM objects with JQuery! @@ -22,9 +39,10 @@ CadQuery has several goals: Using CadQuery, you can write short, simple scripts that produce high quality CAD models. It is easy to make many different objects using a single script that can be customized. + Full Documentation and a Welcoming Community -============================ -You can find the full cadquery documentation at http://dcowden.github.io/cadquery +=============================================== +You can find the full cadquery documentation at `http://dcowden.github.io/cadquery `_ We also have a Google Group to make it easy to get help from other CadQuery users. We want you to feel welcome and encourage you to join the group and introduce yourself. We would also love to hear what you are doing with CadQuery. https://groups.google.com/forum/#!forum/cadquery @@ -43,13 +61,17 @@ It is currently possible to use CadQuery for your own projects in 4 different wa If you are interested in trying CadQuery without installing anything, your best option is to experiment with CadQuery scripts running on a Jupyter server. -[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/RustyVermeer/tryCQ/master) +|BINDER| + +.. |BINDER| image:: https://mybinder.org/badge.svg + :alt: Binder + :target: https://mybinder.org/v2/gh/RustyVermeer/tryCQ/master That button will launch a Jupyter Server pre-configured with CadQuery and its dependencies. It contains a folder with many useful examples to showcase CadQuery's features. ## I'd like to use CadQuery on my own setup -The easiest way to get started with CadQuery is to Install FreeCAD (version 16+) (http://www.freecadweb.org/), and then to use our great CadQuery-FreeCAD plugin here: https://github.com/jmwright/cadquery-freecad-module +The easiest way to get started with CadQuery is to Install FreeCAD (version 16+) (`http://www.freecadweb.org/ `_), and then to use our great CadQuery-FreeCAD plugin here: `https://github.com/jmwright/cadquery-freecad-module `_ It includes the latest version of cadquery already bundled, and has super-easy installation on Mac, Windows, and Unix. @@ -59,9 +81,11 @@ It has tons of awesome features like integration with FreeCAD so you can see you Awesome! CadQuery is built with this attitude in mind. If none of the existing usage methods work for you, you are more than welcome to forge your own path. You'll probably find the most success using the Docker image. You can alternatively install CadQuery as a standalone package. + Getting Started with the docker image ======================================= -The CadQuery docker image (https://hub.docker.com/r/dcowden/cadquery/) includes cadquery and all of its dependencies. It can be used to run cadquery scripts without any installation required ( other than docker, of course) + +The CadQuery docker image (`https://hub.docker.com/r/dcowden/cadquery/ `_) includes cadquery and all of its dependencies. It can be used to run cadquery scripts without any installation required ( other than docker, of course) Examples: @@ -75,7 +99,7 @@ Build a local model using stdin/stdout:: ... STEP output on the console -Build local models and output to the same directory: +Build local models and output to the same directory:: docker run -v $PWD:/home/cq -i dcowden/cadquery:latest build --in_spec Ex001_Simple_Block.py --format STEP INFO: Reading from file 'Ex001_Simple_Block.py' @@ -88,112 +112,109 @@ Build local models and output to the same directory: INFO: Script Generated 1 result Objects INFO: Writing STEP Output to './cqobject-1.STEP' + Projects Using CadQuery ========================= This resin mold was modeled using cadquery and then created on a CNC machine: -

- - -

+|hyOzd_cablefix| |hyOzd_finished| + +.. |hyOzd_cablefix| image:: http://dcowden.github.io/cadquery/_static/hyOzd-cablefix.png + :width: 350 + +.. |hyOzd_finished| image:: http://dcowden.github.io/cadquery/_static/hyOzd-finished.png + :width: 350 The cadquery script is surprisingly short, and allows easily customizing any of the variables:: -```python - import cadquery as cq - from Helpers import show - BS = cq.selectors.BoxSelector - - # PARAMETERS - mount_holes = True - - # mold size - mw = 40 - mh = 13 - ml = 120 - - # wire and fix size - wd = 6 # wire diameter - rt = 7 # resin thickness - rl = 50 # resin length - rwpl = 10 # resin to wire pass length - - # pocket fillet - pf = 18 - - # mount holes - mhd = 7 # hole diameter - mht = 3 # hole distance from edge - - # filling hole - fhd = 6 - - # DRAWING - - # draw base - base = cq.Workplane("XY").box(ml, mw, mh, (True, True, False)) - - # draw wire - pocket = cq.Workplane("XY", (0, 0, mh)).moveTo(-ml/2., 0).line(0, wd/2.)\ - .line((ml-rl)/2.-rwpl, 0).line(rwpl, rt).line(rl, 0)\ - .line(rwpl, -rt).line((ml-rl)/2.-rwpl, 0)\ - .line(0, -(wd/2.)).close().revolve(axisEnd=(1, 0))\ - .edges(BS((-rl/2.-rwpl-.1, -100, -100), (rl/2.+rwpl+.1, 100, 100)))\ - .fillet(pf) - - r = base.cut(pocket) - - # mount holes - if mount_holes: - px = ml/2.-mht-mhd/2. - py = mw/2.-mht-mhd/2 - r = r.faces(" - -

+ # filling hole + fhd = 6 -This Prusa i3 extruder support uses cadquery to build the model (https://github.com/adam-urbanczyk/cadquery-models) : + # DRAWING -

- -

+ # draw base + base = cq.Workplane("XY").box(ml, mw, mh, (True, True, False)) -The mach30 project used cadquery to develop a tool that will create a rocket thruster directly from the appropriate equations (https://opendesignengine.net/projects/yavin-thruster/wiki): -

- -

+ # draw wire + pocket = cq.Workplane("XY", (0, 0, mh)).moveTo(-ml/2., 0).line(0, wd/2.)\ + .line((ml-rl)/2.-rwpl, 0).line(rwpl, rt).line(rl, 0)\ + .line(rwpl, -rt).line((ml-rl)/2.-rwpl, 0)\ + .line(0, -(wd/2.)).close().revolve(axisEnd=(1, 0))\ + .edges(BS((-rl/2.-rwpl-.1, -100, -100), (rl/2.+rwpl+.1, 100, 100)))\ + .fillet(pf) -This example uses Jupyter notebook to produce a really cool web-based scripting environment ( https://github.com/RustyVermeer/avnb/blob/master/readme.md ) : + r = base.cut(pocket) -

- -

+ # mount holes + if mount_holes: + px = ml/2.-mht-mhd/2. + py = mw/2.-mht-mhd/2 + r = r.faces("`_) + +.. image:: https://forum.freecadweb.org/download/file.php?id=33797&sid=b8584f80928497722e9ee9d582a3fa43 + :width: 350 + +This Prusa i3 extruder support uses cadquery to build the model (`https://github.com/adam-urbanczyk/cadquery-models `_): + +.. image:: https://github.com/adam-urbanczyk/cadquery-models/raw/master/extruder_support.png + :width: 350 + +The mach30 project used cadquery to develop a tool that will create a rocket thruster directly from the appropriate equations (`https://opendesignengine.net/projects/yavin-thruster/wiki `_): + +.. image:: http://opendesignengine.net/dmsf_files/480?download= + :width: 700 + +This example uses Jupyter notebook to produce a really cool web-based scripting environment (`https://github.com/RustyVermeer/avnb/blob/master/readme.md `_): + +.. image:: https://github.com/RustyVermeer/cqnb/raw/master/showcase.gif + :width: 350 + We would love to link to your cadquery based project. Just let us know and we'll add it here. @@ -208,10 +229,10 @@ If you are familiar with jQuery, you will probably recognize several jQuery feat * A fluent api to create clean, easy to read code * Language features that make selection and iteration incredibly easy -* * Ability to use the library along side other python libraries * Clear and complete documentation, with plenty of samples. + Why CadQuery instead of OpenSCAD? ======================================== @@ -224,41 +245,47 @@ CadQuery scripts have several key advantages over OpenSCAD: 1. **The scripts use a standard programming language**, python, and thus can benefit from the associated infrastructure. This includes many standard libraries and IDEs -2. **More powerful CAD kernel** OpenCascade is much more powerful than CGAL. Features supported natively +1. **More powerful CAD kernel** OpenCascade is much more powerful than CGAL. Features supported natively by OCC include NURBS, splines, surface sewing, STL repair, STEP import/export, and other complex operations, in addition to the standard CSG operations supported by CGAL -3. **Ability to import/export STEP** We think the ability to begin with a STEP model, created in a CAD package, +1. **Ability to import/export STEP** We think the ability to begin with a STEP model, created in a CAD package, and then add parametric features is key. This is possible in OpenSCAD using STL, but STL is a lossy format -4. **Less Code and easier scripting** CadQuery scripts require less code to create most objects, because it is possible to locate +1. **Less Code and easier scripting** CadQuery scripts require less code to create most objects, because it is possible to locate features based on the position of other features, workplanes, vertices, etc. -5. **Better Performance** CadQuery scripts can build STL, STEP, and AMF faster than OpenSCAD. +1. **Better Performance** CadQuery scripts can build STL, STEP, and AMF faster than OpenSCAD. + License -======== +==================== -CadQuery is licensed under the terms of the Apache Public License, version 2.0. -A copy of the license can be found at http://www.apache.org/licenses/LICENSE-2.0 +CadQuery is licensed under the terms of the `Apache Public License, version 2.0 `_. Ongoing and Future Work -============ +============================= + +CadQuery GUI (under development) +------------------------------------------- + +Work is underway on a stand-alone gui here: `https://github.com/jmwright/cadquery-gui `_ + +CadQuery Parts / Assembly Handling +------------------------------------------- -### CadQuery GUI (under development) -Work is underway on a stand-alone gui here: https://github.com/jmwright/cadquery-gui +Work by Fragmuffin is ongoing with the `cqparts `_ repo. -### CadQuery Parts / Assembly Handling -Work by Fragmuffin is ongoing with the [cqparts](https://github.com/fragmuffin/cqparts) repo. +Moving to Python3 and away from FreeCAD as a dependency +------------------------------------------- -### Moving to Python3 and away from FreeCAD as a dependency -Adam Urbańczyk has been working hard on his own [CQ fork](https://github.com/adam-urbanczyk/cadquery) which uses only PythonOCC instead of FreeCAD. +Adam Urbańczyk has been working hard on his own `CQ fork `_ which uses only PythonOCC instead of FreeCAD. Work has begun on Cadquery 2.0, which will feature: - 1. Feature trees, for more powerful selection - 2. Direct use of OpenCascade Community Edition (OCE), so that it is no longer required to install FreeCAD +1. Feature trees, for more powerful selection +1. Direct use of OpenCascade Community Edition (OCE), so that it is no longer required to install FreeCAD -The project page can be found here: https://github.com/dcowden/cadquery/projects/1 +The project page can be found here: `https://github.com/dcowden/cadquery/projects/1 `_ -A more detailed description of the plan for CQ 2.0 is here: https://docs.google.com/document/d/1cXuxBkVeYmGOo34MGRdG7E3ILypQqkrJ26oVf3CUSPQ +A more detailed description of the plan for CQ 2.0 is `here `_ diff --git a/setup.py b/setup.py index 9de1feb..02cc6c7 100644 --- a/setup.py +++ b/setup.py @@ -30,7 +30,7 @@ author='David Cowden', author_email='dave.cowden@gmail.com', description='CadQuery is a parametric scripting language for creating and traversing CAD models', - long_description=codecs.open('README.md', 'rb', 'UTF-8').read(), + long_description=codecs.open('README.rst', 'rb', 'UTF-8').read(), packages=['cadquery','cadquery.contrib','cadquery.freecad_impl','cadquery.plugins','tests'], install_requires=['pyparsing'], include_package_data=True, From 2f21b0601c29e1709324a6156151b82a517aa1d5 Mon Sep 17 00:00:00 2001 From: Peter Boin Date: Fri, 20 Jul 2018 22:54:51 +1000 Subject: [PATCH 2/3] format fixes --- README.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/README.rst b/README.rst index 1fd4b32..b3eb447 100644 --- a/README.rst +++ b/README.rst @@ -89,15 +89,19 @@ The CadQuery docker image (`https://hub.docker.com/r/dcowden/cadquery/ Date: Fri, 20 Jul 2018 23:01:11 +1000 Subject: [PATCH 3/3] image width units to px --- README.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.rst b/README.rst index b3eb447..53adaad 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ .. image:: http://dcowden.github.io/cadquery/_static/cadquery_logo_dark.svg - :width: 100 + :width: 100px :align: center @@ -125,10 +125,10 @@ This resin mold was modeled using cadquery and then created on a CNC machine: |hyOzd_cablefix| |hyOzd_finished| .. |hyOzd_cablefix| image:: http://dcowden.github.io/cadquery/_static/hyOzd-cablefix.png - :width: 350 + :width: 350px .. |hyOzd_finished| image:: http://dcowden.github.io/cadquery/_static/hyOzd-finished.jpg - :width: 350 + :width: 350px The cadquery script is surprisingly short, and allows easily customizing any of the variables: @@ -204,22 +204,22 @@ Thanks go to cadquery contributor hyOzd ( Altu Technology ) for the example! KiCad uses cadquery to build high quality models of electrictronic components. (`https://github.com/KiCad/packages3D `_) .. image:: https://forum.freecadweb.org/download/file.php?id=33797&sid=b8584f80928497722e9ee9d582a3fa43 - :width: 350 + :width: 350px This Prusa i3 extruder support uses cadquery to build the model (`https://github.com/adam-urbanczyk/cadquery-models `_): .. image:: https://github.com/adam-urbanczyk/cadquery-models/raw/master/extruder_support.png - :width: 350 + :width: 350px The mach30 project used cadquery to develop a tool that will create a rocket thruster directly from the appropriate equations (`https://opendesignengine.net/projects/yavin-thruster/wiki `_): .. image:: http://opendesignengine.net/dmsf_files/480?download= - :width: 700 + :width: 700px This example uses Jupyter notebook to produce a really cool web-based scripting environment (`https://github.com/RustyVermeer/avnb/blob/master/readme.md `_): .. image:: https://github.com/RustyVermeer/cqnb/raw/master/showcase.gif - :width: 350 + :width: 350px We would love to link to your cadquery based project. Just let us know and we'll add it here.