How to debug and contribute code

[Paul8043]

CadQuery is a very interesting approach. I like the programming of the models instead of making "drawings". I have some
background in this direction, I come from OpenSCAD. After spending some days with CadQuery I am considering to
contribute some work to CadQuery.

My short term goal is to get a modified/extended svg-exporter running.

In the long term view I would like to see some improvements in:
* CQ-Editor
* VSCode CadQuery Extension
* CQ-CAM
* cqparts (seems to be very good design, but unfortunately it is broken and no longer maintained)

Now back the my short term goal: a modified/extended svg-exporter

I like to learn which setup is needed to develop some code for cadquery and the other cadquery-companions. If there
is some documentation in this area please let me know. I would also like to understand what kind of workflow you are
using.

What I did so far:
1. My platform is Windows
2. I have set up a python developer environment via mambaforge
3. I have tried to execute the instructions of "contributing code"
   mamba create -n cq-dev -f environment.yml # fails
   # Because it is unclear from where the environment.yml comes from.
   # It seems that cadquery needs to be copied first (via git clone https://github.com/CadQuery/cadquery.git)
   mamba activate cq-dev  # ok
   mamba install -c cadquery -c conda-forge cq-editor=master # ok
   # But this will override cadquery with version that is currently bundled to the cq-editor
   pip install -e . # unclear what it does
   # I have learned the "." represents an arbitrary project directory of cadquery on my local machine
   # maybe by executing
   # cd C:\Users\XXX\workspace
   # git clone https://github.com/CadQuery/cadquery.git
   # which creates C:\Users\XXX\workspace\cadquery
	 
What I have expected to do next:

Checkout with git the branch that belongs to issue #1277:
# unlcear at the moment how issue numbers are mapped to branch names or tags

What I did next:

cd C:\Users\XXX\workspace\cadquery\occ_impl\exporters
edit svg.py
# added a xml-comment into the svg-template

Next commands:

run sq-editor in the dev-environment
execute my model.py which stores to output.svg

I had hoped to the see the xml-comment, I have added in the template, to be part of the output.svg.
But this is NOT the case!

This command sequence was guessed to some extend. The initial steps in a new programming environment
are always hard, especially for newcomers.

The big question is:
To run my model.py I have to execute the code inside of sq-editor. What has to done that sq-editor runs the
local copy of cadquery instead of the version of the dev-environment installation?

I hope you understand what I have tried to achieve. Please let me know what is right way to do it. Any hints
are highly welcome.

[lorenzncode]

Because it is unclear from where the environment.yml comes from.

environment.yml is a file in the cadquery repository. At this point, since you have already created a conda env named "cq-dev" (with working cadquery, cq-editor), you can skip mamba create -n cq-dev -f environment.yml.

You should however install black and mypy (part of the environment.yml dependencies list and useful later):

$ mamba install black=19.10b0 mypy

runs the local copy of cadquery instead of the version of the dev-environment installation?

You can activate your "cq-dev" env, then install cadquery in editable mode with pip.

$ cd C:\Users\XXX\workspace\cadquery
$ conda activate cq-dev
$ pip install -e .

Now try running cq-editor again in this conda env. It will pick up your local cadquery changes.

[Paul8043]

Thanks for providing additional information. I have removed my old "cq-dev" and tried to start again from scratch, just to create a step-by-step-procedure and see whether everything works. I made some progress, but I missed the final target. Something is still missing or I did it wrongly or in the wrong sequence. In the "mamba list" I got an entry for cadquery with revision 0.0.0, but I do not see any entry for
"cq-editor". Why is cq-editor missing? I would also try to run "pytest", just for verification of the setup, but it is also missing. Should be
"cq-editor" and "pytest" in the PATH or is some absolute PATH needed?

Below is the step-by-step-procedure I have tried:

HowTo: Setup a developer environment for CadQuery on Windows

1. create a dedicated python-environment by using miniforge or mambaforge
a) URL: https://github.com/conda-forge/miniforge
b) download mambaforge (Mambaforge-Windows-x86_64.exe)
c) double-click Mambaforge-Windows-x86_64.exe
   -->
   creates a CMD-Window titled "Miniforge Prompt" even it is the mamba-version!
d) all further mamba-commands should be executed from within this "Miniforge Prompt"-window

2. create a developer-environment named "cq-dev"
a) mamba create --name cq-dev
b) mamba env list                       # a line cq-dev should be present now
c) mamba activate cq-dev                # the cq-dev has git the asterisk

e) call all other commands from this window and with "cq-dev" activated

f) mamba deactivate                     # only, if "cq-dev" has been really activated before

3. populate cq-dev with the up-to-date versions of CadQuery and CQ-editor
a) make sure that cq-dev is activated
b) instructions can be found in
   https://github.com/CadQuery/cadquery section "CadQuery Installation Via Conda"
c) mamba install -c conda-forge -c cadquery cadquery=master
d) instructions can be found in
   https://github.com/CadQuery/CQ-editor#installation section "Installation (Anaconda)"
e) mamba install -c cadquery -c conda-forge cq-editor=master

4. clone cadquery from GitHub (CadQuery/cadquery)
a) cd C:\Users\Paul\Workspace
b) git clone https://github.com/CadQuery/cadquery.git
c) cd C:\Users\Paul\Workspace\cadquery   # !!! here all changes will be made later on !!!

5. install additional packages
a) make sure that cq-dev is activated
b) mamba install black=19.10b0 mypy     # additional packages (IMPORTANT)
c) cd C:\Users\Paul\Workspace\cadquery
d) pip install -e .

[lorenzncode]

In the "mamba list" I got an entry for cadquery with revision 0.0.0

Yes, that is a known issue. It will be fixed in #1286.

Why is cq-editor missing?

What was the result of step 3.e?
Try the following to resolve it, starting with the cq-dev conda environment:

conda activate cq-dev
mamba install -c cadquery cq-editor=master

Is this step successful? If so then you can move on to install cadquery using pip in editable mode.

Should be "cq-editor" and "pytest" in the PATH?

Yes cq-editor should be in the path (it is automatically added to the Scripts dir in the conda env on the path at installation).

See the output of where cq-editor in the Miniforge cmd prompt.

Also check:

conda list cq-editor

pytest is part of the environment.yml dependencies. Since you do not use the environment.yml you can install pytest separately with mamba install pytest.

[Paul8043]

I feel myself like Odysseus. The path to a working developer environment is very stony ...

Issue #1286 should not have much impact of what we are doing here. I ignore this for the moment.

I have removed my "cq-dev" by executing:
mamba env remove --name cq-dev

Then I restarted my procedure with step 2.
Step 3c was successful. See output below:

(cq-dev) C:\Users\Paul>mamba list

# packages in environment at C:\Users\Paul\mambaforge\envs\cq-dev:
#
# Name                    Version                   Build  Channel
aiohttp                   3.8.4           py311ha68e1ae_0    conda-forge
aiosignal                 1.3.1              pyhd8ed1ab_0    conda-forge
aom                       3.5.0                h63175ca_0    conda-forge
asttokens                 2.2.1              pyhd8ed1ab_0    conda-forge
async-timeout             4.0.2              pyhd8ed1ab_0    conda-forge
attrs                     22.2.0             pyh71513ae_0    conda-forge
backcall                  0.2.0              pyh9f0ad1d_0    conda-forge
backports                 1.0                pyhd8ed1ab_3    conda-forge
backports.functools_lru_cache 1.6.4              pyhd8ed1ab_0    conda-forge
bzip2                     1.0.8                h8ffe710_4    conda-forge
ca-certificates           2022.12.7            h5b45459_0    conda-forge
cadquery                  master                   py3.11    cadquery
casadi                    3.5.5           py311he26517d_18    conda-forge
charset-normalizer        2.1.1              pyhd8ed1ab_0    conda-forge
colorama                  0.4.6              pyhd8ed1ab_0    conda-forge
curl                      7.88.1               h68f0423_1    conda-forge
decorator                 5.1.1              pyhd8ed1ab_0    conda-forge
double-conversion         3.2.0                h63175ca_1    conda-forge
eigen                     3.4.0                h2d74725_0    conda-forge
executing                 1.2.0              pyhd8ed1ab_0    conda-forge
expat                     2.5.0                h1537add_0    conda-forge
ezdxf                     1.0.2           py311h005e61a_0    conda-forge
ffmpeg                    5.1.2           gpl_h5b1d025_106    conda-forge
font-ttf-dejavu-sans-mono 2.37                 hab24e00_0    conda-forge
font-ttf-inconsolata      3.000                h77eed37_0    conda-forge
font-ttf-source-code-pro  2.038                h77eed37_0    conda-forge
font-ttf-ubuntu           0.83                 hab24e00_0    conda-forge
fontconfig                2.14.2               hbde0cde_0    conda-forge
fonts-conda-ecosystem     1                             0    conda-forge
fonts-conda-forge         1                             0    conda-forge
freeimage                 3.18.0              h30d40d2_12    conda-forge
freetype                  2.12.1               h546665d_1    conda-forge
frozenlist                1.3.3           py311ha68e1ae_0    conda-forge
gettext                   0.21.1               h5728263_0    conda-forge
gl2ps                     1.4.2                h0597ee9_0    conda-forge
glew                      2.1.0                h39d44d4_2    conda-forge
glib                      2.74.1               h12be248_1    conda-forge
glib-tools                2.74.1               h12be248_1    conda-forge
gst-plugins-base          1.22.0               h001b923_2    conda-forge
gstreamer                 1.22.0               h6b5321d_2    conda-forge
hdf4                      4.2.15               h1b1b6ef_5    conda-forge
hdf5                      1.12.2          nompi_h57737ce_101    conda-forge
icu                       70.1                 h0e60522_0    conda-forge
idna                      3.4                pyhd8ed1ab_0    conda-forge
imath                     3.1.6                h12be248_1    conda-forge
intel-openmp              2023.0.0         h57928b3_25922    conda-forge
ipopt                     3.14.11              ha9547d1_0    conda-forge
ipython                   8.11.0             pyh08f2357_0    conda-forge
jedi                      0.18.2             pyhd8ed1ab_0    conda-forge
jpeg                      9e                   hcfcfb64_3    conda-forge
jsoncpp                   1.9.5                h2d74725_1    conda-forge
jxrlib                    1.1                  h8ffe710_2    conda-forge
krb5                      1.20.1               heb0366b_0    conda-forge
lcms2                     2.15                 ha5c8aab_0    conda-forge
lerc                      4.0.0                h63175ca_0    conda-forge
libaec                    1.0.6                h63175ca_1    conda-forge
libblas                   3.9.0              16_win64_mkl    conda-forge
libcblas                  3.9.0              16_win64_mkl    conda-forge
libclang                  15.0.7          default_h77d9078_1    conda-forge
libclang13                15.0.7          default_h77d9078_1    conda-forge
libcurl                   7.88.1               h68f0423_1    conda-forge
libdeflate                1.17                 hcfcfb64_0    conda-forge
libffi                    3.4.2                h8ffe710_5    conda-forge
libflang                  5.0.0           h6538335_20180525    conda-forge
libglib                   2.74.1               he8f3873_1    conda-forge
libhwloc                  2.9.0                h51c2c0f_0    conda-forge
libiconv                  1.17                 h8ffe710_0    conda-forge
liblapack                 3.9.0              16_win64_mkl    conda-forge
libnetcdf                 4.9.1           nompi_hc41bf00_101    conda-forge
libogg                    1.3.4                h8ffe710_1    conda-forge
libopus                   1.3.1                h8ffe710_1    conda-forge
libosqp                   0.6.2                h63175ca_4    conda-forge
libpng                    1.6.39               h19919ed_0    conda-forge
libqdldl                  0.1.5                h63175ca_1    conda-forge
libraw                    0.21.1               h3eb7d9d_0    conda-forge
libsqlite                 3.40.0               hcfcfb64_0    conda-forge
libssh2                   1.10.0               h9a1e1f7_3    conda-forge
libtheora                 1.1.1             h8d14728_1005    conda-forge
libtiff                   4.5.0                hf8721a0_2    conda-forge
libvorbis                 1.3.7                h0e60522_0    conda-forge
libwebp-base              1.3.0                hcfcfb64_0    conda-forge
libxml2                   2.10.3               hc3477c8_6    conda-forge
libzip                    1.9.2                h519de47_1    conda-forge
libzlib                   1.2.13               hcfcfb64_4    conda-forge
llvm-meta                 5.0.0                         0    conda-forge
loguru                    0.6.0           py311h1ea47a8_2    conda-forge
lz4-c                     1.9.4                hcfcfb64_0    conda-forge
matplotlib-inline         0.1.6              pyhd8ed1ab_0    conda-forge
metis                     5.1.0             h0e60522_1006    conda-forge
mkl                       2022.1.0           h6a75c08_874    conda-forge
multidict                 6.0.4           py311ha68e1ae_0    conda-forge
multimethod               1.9.1              pyhd8ed1ab_0    conda-forge
mumps-seq                 5.2.1               hb3f9cae_11    conda-forge
nlohmann_json             3.11.2               h39d44d4_0    conda-forge
nlopt                     2.7.1           py311h6e294a0_3    conda-forge
nptyping                  2.5.0              pyhd8ed1ab_0    conda-forge
numpy                     1.24.2          py311h0b4df5a_0    conda-forge
occt                      7.7.0                h54f5ab0_2    conda-forge
ocp                       7.7.0.0         py311hab9c202_1    conda-forge
openexr                   3.1.5                h97333cc_2    conda-forge
openh264                  2.3.1                h63175ca_2    conda-forge
openjpeg                  2.5.0                ha2aaf27_2    conda-forge
openmp                    5.0.0                    vc14_1    conda-forge
openssl                   3.1.0                hcfcfb64_0    conda-forge
parso                     0.8.3              pyhd8ed1ab_0    conda-forge
pcre2                     10.40                h17e33f8_0    conda-forge
pickleshare               0.7.5                   py_1003    conda-forge
pip                       23.0.1             pyhd8ed1ab_0    conda-forge
proj                      9.1.1                heca977f_2    conda-forge
prompt-toolkit            3.0.38             pyha770c72_0    conda-forge
prompt_toolkit            3.0.38               hd8ed1ab_0    conda-forge
pthreads-win32            2.9.1                hfa6e2cd_3    conda-forge
pugixml                   1.11.4               h0e60522_0    conda-forge
pure_eval                 0.2.2              pyhd8ed1ab_0    conda-forge
pybind11-abi              4                    hd8ed1ab_3    conda-forge
pygments                  2.14.0             pyhd8ed1ab_0    conda-forge
pyparsing                 3.0.9              pyhd8ed1ab_0    conda-forge
python                    3.11.0          hcf16a7b_0_cpython    conda-forge
python_abi                3.11                    3_cp311    conda-forge
qt-main                   5.15.8               h720456b_6    conda-forge
rapidjson                 1.1.0             ha925a31_1002    conda-forge
setuptools                67.6.0             pyhd8ed1ab_0    conda-forge
six                       1.16.0             pyh6c4a22f_0    conda-forge
sqlite                    3.40.0               hcfcfb64_0    conda-forge
stack_data                0.6.2              pyhd8ed1ab_0    conda-forge
svt-av1                   1.4.1                h63175ca_0    conda-forge
tbb                       2021.8.0             h91493d7_0    conda-forge
tbb-devel                 2021.8.0             h91493d7_0    conda-forge
tk                        8.6.12               h8ffe710_0    conda-forge
traitlets                 5.9.0              pyhd8ed1ab_0    conda-forge
typing-extensions         4.5.0                hd8ed1ab_0    conda-forge
typing_extensions         4.5.0              pyha770c72_0    conda-forge
typish                    1.9.3              pyhd8ed1ab_0    conda-forge
tzdata                    2022g                h191b570_0    conda-forge
ucrt                      10.0.22621.0         h57928b3_0    conda-forge
utfcpp                    3.2.3                h57928b3_0    conda-forge
vc                        14.3                hb6edc58_10    conda-forge
vs2015_runtime            14.34.31931         h4c5c07a_10    conda-forge
vtk                       9.2.5           qt_py311hd10cacf_203    conda-forge
wcwidth                   0.2.6              pyhd8ed1ab_0    conda-forge
wheel                     0.40.0             pyhd8ed1ab_0    conda-forge
win32_setctime            1.1.0              pyhd8ed1ab_0    conda-forge
wslink                    1.10.1             pyhd8ed1ab_0    conda-forge
x264                      1!164.3095           h8ffe710_2    conda-forge
x265                      3.5                  h2d74725_3    conda-forge
xz                        5.2.6                h8d14728_0    conda-forge
yarl                      1.8.2           py311ha68e1ae_0    conda-forge
zlib                      1.2.13               hcfcfb64_4    conda-forge
zstd                      1.5.2                h12be248_6    conda-forge

(cq-dev) C:\Users\Paul>

Step 3e failed. See output below:

(cq-dev) C:\Users\Paul>mamba install -c cadquery -c conda-forge cq-editor=master

Looking for: ['cq-editor=master']

conda-forge/win-64                                          Using cache
conda-forge/noarch                                          Using cache
pkgs/r/win-64                                                 No change
pkgs/main/win-64                                              No change
pkgs/main/noarch                                              No change
pkgs/msys2/noarch                                             No change
pkgs/r/noarch                                                 No change
pkgs/msys2/win-64                                             No change
cadquery/noarch                                               No change
cadquery/win-64                                               No change

Pinned packages:
  - python 3.11.*


Could not solve for environment specs
Encountered problems while solving:
  - package cq-editor-master-py3.9 requires python >=3.9,<3.10.0a0, but none of the providers can be installed

The environment can't be solved, aborting the operation

(cq-dev) C:\Users\Paul>

Some things need further clarification:

1. The channel specification "-c conda-forge -c cadquery" is used for cadquery, but for cq-editor it is swapped to
   "-c cadquery -c conda-forge". Does this have any relevance in our context?
2. Would it not be better to install only "sq-editor", because it has an internal dependency to "cadquery". This would
   guarantee that both fit together. However the version of "cadquery" might be older, and not the one I planned to
   use later on. How to overcome these difficulties. "cadquery" and cq-editor" are very close friends.
3. "cq-editor" is needed to verify the rendered output of a model. However the debugging capabilities are very limitted
   at the moment. Would it be possible to use a more sophisticated debugger (like VSCode or PyCharm, Spyder) and
   still see the graphical output in an extra window? But it seems the the show_object()-calls work only together with
   "cq-editor".

[lorenzncode]

Pinned packages:

• python 3.11.*

cq-editor does not currently support python 3.11 - conda packages are not built for 3.11.

I'd suggest to create a new conda env with python 3.10. Then proceed with the install.

mamba instal python=3.10

1. The channel specification "-c conda-forge -c cadquery" is used for cadquery

miniforge/mambaforge set conda-forge as the default channel. You can omit -c conda-forge on the command line.

2. Would it not be better to install only "cq-editor",

The instructions suggest to install from the environment.yml file. Yes, it's possible to skip that and install cq-editor which brings cadquery. Again, you then need to manually install the other dev dependencies.

3. Would it be possible to use a more sophisticated debugger (like VSCode ...

Yes, you can use an external text editor of your choice and use cq-editor as the model viewer.

• Toggle the visibility of the text editor to off; View->Editor
• Enable Autoreload to reload when changes are made to the file; Edit->Preferences->Code Editor->Autoreload

Say your cadquery script is myscript.py.

• Open myscript.py in vscode
• Open myscript.py in cq-editor (the Editor widget may be hidden)
  Use either File->Open or from CLI: cq-editor myscript.py
• Select Render in cq-editor
• Make changes to your script in vscode
  The model is automatically rendered again

it seems the the show_object()-calls work only together with "cq-editor".

Yes, show_object is provided by cq-editor. Call show_object when rendering in cq-editor (whether or not you are using the Editor widget for editing the script).

To run your script standalone, outside cq-editor (say for the purpose of exporting to STEP) you must comment out or remove the show_object call.

If you would like to run your script in cq-editor or standalone, without changes to the script, you can conditionally call show_object:

if "show_object" in locals():
    show_object(result)

[Paul8043]

The puzzle is almost complete ...

Here is my improved step-by-step procedure:

HowTo: Setup a developer environment for CadQuery on Windows

1. create a dedicated python-environment by using miniforge or mambaforge
a) URL: https://github.com/conda-forge/miniforge
b) download mambaforge (Mambaforge-Windows-x86_64.exe)
c) double-click Mambaforge-Windows-x86_64.exe
   -->
	 creates a CMD-Window titled "Miniforge Prompt" even it is the mamba-version!
d) all further mamba-commands should be executed from within this "Miniforge Prompt"-window

2. create a developer-environment named "cq-dev"
a) mamba create --name cq-dev
b) mamba env list                       # a line cq-dev should be present now
c) mamba activate cq-dev                # the cq-dev has git the asterisk

e) call all other commands from this window and with "cq-dev" activated

f) mamba deactivate                     # only, if "cq-dev" has been really activated before

3. populate cq-dev with the up-to-date versions of CadQuery and CQ-editor
a) make sure that cq-dev is activated
b) mamba install -c cadquery python=3.10 cadquery=master cq-editor=master
c) mamba list                           # check, whether all 3 packages are part of the list

4. install additional packages
a) make sure that cq-dev is activated
b) mamba install black=19.10b0 mypy pytest    # additional packages (IMPORTANT)
c) mamba list                                 # check versions

5. clone cadquery from GitHub (CadQuery/cadquery)
a) cd C:\Users\Paul\Workspace
b) git clone https://github.com/CadQuery/cadquery.git
c) cd C:\Users\Paul\Workspace\cadquery        # !!! here all changes will be made later on !!!
d) pip install -e .                           # reinstalling cadquery using pip

6. verify installation
a) cd C:\Users\Paul\Workspace\cadquery
b) pytest --version                           # check whether pvtest is pressent
c) pytest                                     # run pytest
d) sq-editor --help                           # check whether cq-editor is present

7. verify which cadquery code is executed
a) md C:\Users\Paul\Workspace\myscript
b) cd C:\Users\Paul\Workspace\myscript
b) notepad++ myscript.py                      # create a simple model
c) cq-editor myscript.py
d) run                                        # will create output.svg
e) rename output.svg output_org.svg           # rename file

f) cd C:\Users\Paul\Workspace\cadquery\cadquery\occ_impl\exporters
g) notepad++ svg.py                           # add a xml comment

h) cd C:\Users\Paul\Workspace\myscript
i) notepad++ myscript.py                      # create a simple model
j) cq-editor myscript.py
k) run                                        # will create output.svg
l) more output.svg                            # check whether added xml-comment is present or not

I have restarted from scratch again by calling first

mamba env remove --name cq-dev

and then I have executed the procedure beginning with step 2. Now the steps from 2 to 6 are successful. All
packages are present and I can call all tools incl. pytest.

I have added step 7, just to see which cadquery-code is executed. For this purpose I have created a simple "myscript.py"
with the contents below:

# myscript.py

import cadquery as cq
from cadquery import exporters

part = cq.Workplane("XY").rect(100,100,centered=False)

show_object(part,name="part",options={"alpha":0.2,"color":(255,170,0)})

exporters.export(
        part,
        'output.svg',
        opt={
            "width": 100,
            "height": 100,
            "marginLeft": 0,
            "marginTop": 0,
            "showAxes": False,
            "projectionDir": (0.0,0.0,1.0),
            "strokeWidth": 0.2,
            "strokeColor": (255, 0, 0),
            "hiddenColor": (0, 0, 255),
            "showHidden": False,
        },
    )

This will create an output-file named "output.svg". With step 7g I make a small modification inside svg.py in my
local copy of cadquery. I have only added line 23. See below:

import io as StringIO

from ..shapes import Shape, Compound, TOLERANCE
from ..geom import BoundBox


from OCP.gp import gp_Ax2, gp_Pnt, gp_Dir
from OCP.BRepLib import BRepLib
from OCP.HLRBRep import HLRBRep_Algo, HLRBRep_HLRToShape
from OCP.HLRAlgo import HLRAlgo_Projector
from OCP.GCPnts import GCPnts_QuasiUniformDeflection

DISCRETIZATION_TOLERANCE = 1e-3

SVG_TEMPLATE = """<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
   xmlns:svg="http://www.w3.org/2000/svg"
   xmlns="http://www.w3.org/2000/svg"
   width="%(width)s"
   height="%(height)s"

>
    <!-- Eureka, we have it -->
    <g transform="scale(%(unitScale)s, -%(unitScale)s)   translate(%(xTranslate)s,%(yTranslate)s)" stroke-width="%(strokeWidth)s"  fill="none">
       <!-- hidden lines -->
       <g  stroke="rgb(%(hiddenColor)s)" fill="none" stroke-dasharray="%(strokeWidth)s,%(strokeWidth)s" >
%(hiddenContent)s
       </g>

       <!-- solid lines -->
       <g  stroke="rgb(%(strokeColor)s)" fill="none">
%(visibleContent)s
       </g>
    </g>
    %(axesIndicator)s
</svg>
"""

# The axes indicator - needs to be replaced with something dynamic eventually
AXES_TEMPLATE = """<g transform="translate(20,%(textboxY)s)" stroke="rgb(0,0,255)">
        <line x1="30" y1="-30" x2="75" y2="-33" stroke-width="3" stroke="#000000" />
         <text x="80" y="-30" style="stroke:#000000">X </text>

        <line x1="30" y1="-30" x2="30" y2="-75" stroke-width="3" stroke="#000000" />
         <text x="25" y="-85" style="stroke:#000000">Y </text>

        <line x1="30" y1="-30" x2="58" y2="-15" stroke-width="3" stroke="#000000" />
         <text x="65" y="-5" style="stroke:#000000">Z </text>
        <!--
            <line x1="0" y1="0" x2="%(unitScale)s" y2="0" stroke-width="3" />
            <text x="0" y="20" style="stroke:#000000">1  %(uom)s </text>
        -->
    </g>"""

PATHTEMPLATE = '\t\t\t<path d="%s" />\n'


class UNITS:
    MM = "mm"
    IN = "in"


def guessUnitOfMeasure(shape):
    """
    Guess the unit of measure of a shape.
    """
    bb = BoundBox._fromTopoDS(shape.wrapped)

    dimList = [bb.xlen, bb.ylen, bb.zlen]
    # no real part would likely be bigger than 10 inches on any side
    if max(dimList) > 10:
        return UNITS.MM

    # no real part would likely be smaller than 0.1 mm on all dimensions
    if min(dimList) < 0.1:
        return UNITS.IN

    # no real part would have the sum of its dimensions less than about 5mm
    if sum(dimList) < 10:
        return UNITS.IN

    return UNITS.MM


def makeSVGedge(e):
    """
    Creates an SVG edge from a OCCT edge.
    """

    cs = StringIO.StringIO()

    curve = e._geomAdaptor()  # adapt the edge into curve
    start = curve.FirstParameter()
    end = curve.LastParameter()

    points = GCPnts_QuasiUniformDeflection(curve, DISCRETIZATION_TOLERANCE, start, end)

    if points.IsDone():
        point_it = (points.Value(i + 1) for i in range(points.NbPoints()))

        p = next(point_it)
        cs.write("M{},{} ".format(p.X(), p.Y()))

        for p in point_it:
            cs.write("L{},{} ".format(p.X(), p.Y()))

    return cs.getvalue()


def getPaths(visibleShapes, hiddenShapes):
    """
    Collects the visible and hidden edges from the CadQuery object.
    """

    hiddenPaths = []
    visiblePaths = []

    for s in visibleShapes:
        for e in s.Edges():
            visiblePaths.append(makeSVGedge(e))

    for s in hiddenShapes:
        for e in s.Edges():
            hiddenPaths.append(makeSVGedge(e))

    return (hiddenPaths, visiblePaths)


def getSVG(shape, opts=None):
    """
    Export a shape to SVG text.

    :param shape: A CadQuery shape object to convert to an SVG string.
    :type Shape: Vertex, Edge, Wire, Face, Shell, Solid, or Compound.
    :param opts: An options dictionary that influences the SVG that is output.
    :type opts: Dictionary, keys are as follows:
        width: Document width of the resulting image.
        height: Document height of the resulting image.
        marginLeft: Inset margin from the left side of the document.
        marginTop: Inset margin from the top side of the document.
        projectionDir: Direction the camera will view the shape from.
        showAxes: Whether or not to show the axes indicator, which will only be
                  visible when the projectionDir is also at the default.
        strokeWidth: Width of the line that visible edges are drawn with.
        strokeColor: Color of the line that visible edges are drawn with.
        hiddenColor: Color of the line that hidden edges are drawn with.
        showHidden: Whether or not to show hidden lines.
        focus: If specified, creates a perspective SVG with the projector
               at the distance specified.
    """

    # Available options and their defaults
    d = {
        "width": 800,
        "height": 240,
        "marginLeft": 200,
        "marginTop": 20,
        "projectionDir": (-1.75, 1.1, 5),
        "showAxes": True,
        "strokeWidth": -1.0,  # -1 = calculated based on unitScale
        "strokeColor": (0, 0, 0),  # RGB 0-255
        "hiddenColor": (160, 160, 160),  # RGB 0-255
        "showHidden": True,
        "focus": None,
    }

    if opts:
        d.update(opts)

    # need to guess the scale and the coordinate center
    uom = guessUnitOfMeasure(shape)

    width = float(d["width"])
    height = float(d["height"])
    marginLeft = float(d["marginLeft"])
    marginTop = float(d["marginTop"])
    projectionDir = tuple(d["projectionDir"])
    showAxes = bool(d["showAxes"])
    strokeWidth = float(d["strokeWidth"])
    strokeColor = tuple(d["strokeColor"])
    hiddenColor = tuple(d["hiddenColor"])
    showHidden = bool(d["showHidden"])
    focus = float(d["focus"]) if d.get("focus") else None

    hlr = HLRBRep_Algo()
    hlr.Add(shape.wrapped)

    coordinate_system = gp_Ax2(gp_Pnt(), gp_Dir(*projectionDir))

    if focus is not None:
        projector = HLRAlgo_Projector(coordinate_system, focus)
    else:
        projector = HLRAlgo_Projector(coordinate_system)

    hlr.Projector(projector)
    hlr.Update()
    hlr.Hide()

    hlr_shapes = HLRBRep_HLRToShape(hlr)

    visible = []

    visible_sharp_edges = hlr_shapes.VCompound()
    if not visible_sharp_edges.IsNull():
        visible.append(visible_sharp_edges)

    visible_smooth_edges = hlr_shapes.Rg1LineVCompound()
    if not visible_smooth_edges.IsNull():
        visible.append(visible_smooth_edges)

    visible_contour_edges = hlr_shapes.OutLineVCompound()
    if not visible_contour_edges.IsNull():
        visible.append(visible_contour_edges)

    hidden = []

    hidden_sharp_edges = hlr_shapes.HCompound()
    if not hidden_sharp_edges.IsNull():
        hidden.append(hidden_sharp_edges)

    hidden_contour_edges = hlr_shapes.OutLineHCompound()
    if not hidden_contour_edges.IsNull():
        hidden.append(hidden_contour_edges)

    # Fix the underlying geometry - otherwise we will get segfaults
    for el in visible:
        BRepLib.BuildCurves3d_s(el, TOLERANCE)
    for el in hidden:
        BRepLib.BuildCurves3d_s(el, TOLERANCE)

    # convert to native CQ objects
    visible = list(map(Shape, visible))
    hidden = list(map(Shape, hidden))
    (hiddenPaths, visiblePaths) = getPaths(visible, hidden)

    # get bounding box -- these are all in 2D space
    bb = Compound.makeCompound(hidden + visible).BoundingBox()

    # width pixels for x, height pixels for y
    unitScale = min(width / bb.xlen * 0.75, height / bb.ylen * 0.75)

    # compute amount to translate-- move the top left into view
    (xTranslate, yTranslate) = (
        (0 - bb.xmin) + marginLeft / unitScale,
        (0 - bb.ymax) - marginTop / unitScale,
    )

    # If the user did not specify a stroke width, calculate it based on the unit scale
    if strokeWidth == -1.0:
        strokeWidth = 1.0 / unitScale

    # compute paths
    hiddenContent = ""

    # Prevent hidden paths from being added if the user disabled them
    if showHidden:
        for p in hiddenPaths:
            hiddenContent += PATHTEMPLATE % p

    visibleContent = ""
    for p in visiblePaths:
        visibleContent += PATHTEMPLATE % p

    # If the caller wants the axes indicator and is using the default direction, add in the indicator
    if showAxes and projectionDir == (-1.75, 1.1, 5):
        axesIndicator = AXES_TEMPLATE % (
            {"unitScale": str(unitScale), "textboxY": str(height - 30), "uom": str(uom)}
        )
    else:
        axesIndicator = ""

    svg = SVG_TEMPLATE % (
        {
            "unitScale": str(unitScale),
            "strokeWidth": str(strokeWidth),
            "strokeColor": ",".join([str(x) for x in strokeColor]),
            "hiddenColor": ",".join([str(x) for x in hiddenColor]),
            "hiddenContent": hiddenContent,
            "visibleContent": visibleContent,
            "xTranslate": str(xTranslate),
            "yTranslate": str(yTranslate),
            "width": str(width),
            "height": str(height),
            "textboxY": str(height - 30),
            "uom": str(uom),
            "axesIndicator": axesIndicator,
        }
    )

    return svg


def exportSVG(shape, fileName: str, opts=None):
    """
    Accept a cadquery shape, and export it to the provided file
    TODO: should use file-like objects, not a fileName, and/or be able to return a string instead
    export a view of a part to svg
    """

    svg = getSVG(shape.val(), opts)
    f = open(fileName, "w")
    f.write(svg)
    f.close()

After this modification I have run "myscript.py" again with the hope that the added xml-comment appears in
"output.svg". But this is not the case. What went wrong or is missing?

[lorenzncode]

What is the output of conda list cadquery with cq-dev active?

[Paul8043]

Same procedure as every day ...
Hard work pays ...

It seems yesterday I did not perform exactly what my step-by-step procedure has told me! My fault, today the re-execution of the command-list was successful!

@lorenzncode great thanks to you for your help and your patience.

"cq-editor" has really run the code from my local "cadquery". Below is the expected result:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
   xmlns:svg="http://www.w3.org/2000/svg"
   xmlns="http://www.w3.org/2000/svg"
   width="100.0"
   height="100.0"

>
    <!-- Eureka, we have it -->
    <g transform="scale(0.75, -0.75)   translate(0.0,-100.0)" stroke-width="0.2"  fill="none">
       <!-- hidden lines -->
       <g  stroke="rgb(0,0,255)" fill="none" stroke-dasharray="0.2,0.2" >

       </g>

       <!-- solid lines -->
       <g  stroke="rgb(255,0,0)" fill="none">
			<path d="M0.0,0.0 L100.0,0.0 " />
			<path d="M100.0,0.0 L100.0,100.0 " />
			<path d="M100.0,100.0 L0.0,100.0 " />
			<path d="M0.0,100.0 L0.0,0.0 " />

       </g>
    </g>
    
</svg>

Outlook for the next days. I will create some real models with cadquery. And after that I will come back to issue #1282.

Again, big thanks to the entire cadquery-team, this is great work.

[adam-urbanczyk]

FYI: CQ-editor now builds as noarch so should be installable with 3.11

[lorenzncode]

Good to hear @Paul8043.

FYI: CQ-editor now builds as noarch so should be installable with 3.11

Thanks @adam-urbanczyk - confirmed working for me on Linux, and Windows.
mamba install -c cadquery python=3.11 cq-editor=master

[Paul8043]

May I come back to the proposal with the "environment.yml" mentioned in Readme.md, section "contributing code".

Create a conda development environment with something like:

conda env create -n cq-dev -f environment.yml

With the learnings from the last days I know the "environment.yml" is part of the "cadquery"-package. So, fetching of "cadquery" might be the first step. But then, it is still unclear which context is needed for this command. I have tried the following:

HowTo: Setup a developer environment for CadQuery on Windows (with environment.yml)

1. create a dedicated python-environment by using miniforge or mambaforge
a) URL: https://github.com/conda-forge/miniforge
b) download mambaforge (Mambaforge-Windows-x86_64.exe)
c) double-click Mambaforge-Windows-x86_64.exe
   -->
	 creates a CMD-Window titled "Miniforge Prompt" even it is the mamba-version!
d) all further mamba-commands should be executed from within this "Miniforge Prompt"-window

2. clone cadquery from GitHub (CadQuery/cadquery) to get environment.yml
a) cd C:\Users\Paul\Workspace
b) git clone https://github.com/CadQuery/cadquery.git
c) cd C:\Users\Paul\Workspace\cadquery
d) more environment.yml

3. create a developer-environment named "xxx-dev"
a) open mambaforge Prompt Window
b) cd C:\Users\Paul\Workspace\cadquery
c) mamba create -n xxx-dev -f environment.yml python=3.10
d) mamba env list                       # a line xxx-dev should be present now
e) mamba activate xxx-dev               # the xxx-dev has got the asterisk
f) mamba list                           # check, what you have got

But step 3c fails. I have pinned python=3.10, knowing that this is no longer necessary, because you have
upgraded the code to 3.11. However this is not the reason why it fails. I have got the following output:

(base) C:\Users\Paul\Projects\Workspace\cadquery>more environment.yml
name: cadquery
channels:
  - cadquery
  - conda-forge
dependencies:
  - python>=3.8
  - ipython
  - ocp=7.7.*
  - pyparsing>=2.1.9
  - sphinx=5.0.1
  - sphinx_rtd_theme
  - black=19.10b0
  - click=8.0.4
  - mypy
  - codecov
  - pytest
  - pytest-cov
  - ezdxf
  - ipython
  - typing_extensions
  - nptyping=2.0.1
  - nlopt
  - path
  - casadi
  - multimethod >=1.7,<2.0
  - pip
  - pip:
    - --editable=.
    - git+https://github.com/CadQuery/OCP-stubs.git

(base) C:\Users\Paul\Projects\Workspace\cadquery>mamba env list
# conda environments:
#
base                  *  C:\Users\Paul\mambaforge
cq-dev                   C:\Users\Paul\mambaforge\envs\cq-dev
cqe-env                  C:\Users\Paul\mambaforge\envs\cqe-env


(base) C:\Users\Paul\Projects\Workspace\cadquery>mamba create -n xxx-dev -f environment.yml python=3.10

                  __    __    __    __
                 /  \  /  \  /  \  /  \
                /    \/    \/    \/    \
███████████████/  /██/  /██/  /██/  /████████████████████████
              /  / \   / \   / \   / \  \____
             /  /   \_/   \_/   \_/   \    o \__,
            / _/                       \_____/  `
            |/
        ███╗   ███╗ █████╗ ███╗   ███╗██████╗  █████╗
        ████╗ ████║██╔══██╗████╗ ████║██╔══██╗██╔══██╗
        ██╔████╔██║███████║██╔████╔██║██████╔╝███████║
        ██║╚██╔╝██║██╔══██║██║╚██╔╝██║██╔══██╗██╔══██║
        ██║ ╚═╝ ██║██║  ██║██║ ╚═╝ ██║██████╔╝██║  ██║
        ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝╚═════╝ ╚═╝  ╚═╝

        mamba (1.1.0) supported by @QuantStack

        GitHub:  https://github.com/mamba-org/mamba
        Twitter: https://twitter.com/QuantStack

█████████████████████████████████████████████████████████████


Looking for: ['environment.yml', 'python=3.10']

pkgs/main/win-64                                              No change
pkgs/r/win-64                                                 No change
pkgs/main/noarch                                              No change
pkgs/r/noarch                                                 No change
pkgs/msys2/win-64                                             No change
pkgs/msys2/noarch                                             No change
conda-forge/noarch                                  11.7MB @   4.3MB/s  3.5s
conda-forge/win-64                                  19.7MB @   3.9MB/s  6.8s
Could not solve for environment specs
Encountered problems while solving:
  - nothing provides requested environment.yml

The environment can't be solved, aborting the operation


(base) C:\Users\Paul\Projects\Workspace\cadquery>

What is missing, it seems that the context is still incomplete?

[lorenzncode]

The command to create an environment based on a definition file mamba env create is not the same as the command to create an env from a list of packages mamba create.

The correct command is:
mamba env create -n cqdev -f environment.yml

or (if environment.yml exists in the current working directory):
mamba env create -n cqdev

To specify the python version you could edit the environment.yml definition file.

[Paul8043]

Oh, I see there is a small difference! I got fooled by the subtle command-line interface of mamba. Below is the complete sequence, if the environment should be created based on an environment.yml.

HowTo: Setup a developer environment for CadQuery on Windows (with environment.yml)

1. create a dedicated python-environment by using miniforge or mambaforge
a) URL: https://github.com/conda-forge/miniforge
b) download mambaforge (Mambaforge-Windows-x86_64.exe)
c) double-click Mambaforge-Windows-x86_64.exe
   -->
	 creates a CMD-Window titled "Miniforge Prompt" even it is the mamba-version!
d) all further mamba-commands should be executed from within this "Miniforge Prompt"-window

2. clone cadquery from GitHub (CadQuery/cadquery) to get environment.yml
a) cd C:\Users\Paul\Workspace
b) git clone https://github.com/CadQuery/cadquery.git
c) cd C:\Users\Paul\Workspace\cadquery
d) more environment.yml

3. create a developer-environment named "xxx-dev"
a) open mambaforge Prompt Window
b) cd C:\Users\Paul\Workspace\cadquery
c) mamba env create -n xxx-dev -f environment.yml python=3.11
d) mamba env list                       # a line xxx-dev should be present now
e) mamba activate xxx-dev               # the xxx-dev has got the asterisk
f) mamba list                           # check, what you have got

4. populate xxx-dev with the up-to-date versions of CadQuery and CQ-editor
a) make sure that xxx-dev is activated
b) mamba install -c cadquery cadquery=master cq-editor=master
c) mamba list                           # check, whether all 3 packages are part of the list

5. verify installation
a) cd C:\Users\Paul\Workspace\cadquery
b) pytest --version                           # check whether pvtest is pressent
c) pytest                                     # run pytest
d) sq-editor --help                           # check whether cq-editor is present

6. reinstalling cadquery using pip
c) cd C:\Users\Paul\Workspace\cadquery        # !!! here all changes will be made later on !!!
d) pip install -e .                           # reinstalling cadquery using pip
e) mamba list                                 # check versions

7. verify which cadquery code is executed
a) md C:\Users\Paul\Workspace\myscript
b) cd C:\Users\Paul\Workspace\myscript
b) notepad++ myscript.py                      # create a simple model
c) cq-editor myscript.py
d) run                                        # will create output.svg
e) rename output.svg output_org.svg           # rename file

f) cd C:\Users\Paul\Workspace\cadquery\cadquery\occ_impl\exporters
g) notepad++ svg.py                           # add a xml comment

h) cd C:\Users\Paul\Workspace\myscript
i) notepad++ myscript.py                      # create a simple model
j) cq-editor myscript.py
k) run                                        # will create output.svg
l) more output.svg                            # check whether added xml-comment is present or not