Docs

Developer

This is documentation is intended for developers wishing to modify or extend Inkcut.

Building from source

To build from source use the commands below.

We intend to support both Python 2 (with qt 4) and Python 3 (with qt 5), however using Python 3 is recommended. On 32-bit systems only Python 2 works, since PyQt5 only has a 64-bit package.

Python 3 (Recommended)

virtualenv -p python3 venv
source venv/bin/activate

# Install native dependencies
sudo apt install libxml2-dev libxslt-dev libcups2-dev

# Install python dependencies
pip install PyQt5

# Run inkcut from sources
python main.py

# Install inkcut
pip install .
NOTES:
  1. Install commands should be run from the folder Inkcut is cloned/downloaded into using either cd /path/to/inkcut/folder
  2. If pip install . gives an error regarding enamlx, you may need to install enamlx, then re-run pip install . In Ubuntu 16, this can be done by: pip install git+https://github.com/frmdstryr/enamlx.git.

Python 2

virtualenv -p python2 venv
source venv/bin/activate

# Install lxml
sudo apt install libxml2-dev libxslt-dev

# Only on Python 2 - you must install and link pyqt4
sudo apt install python-qt4

#: Replace ~/.virtualenvs/cv with venv/ on linux
ln -s /usr/lib/python2.7/dist-packages/PyQt4/ ~/.virtualenvs/cv/lib/python2.7/site-packages/
ln -s /usr/lib/python2.7/dist-packages/sip.so ~/.virtualenvs/cv/lib/python2.7/site-packages/

#: Install inkcut
pip install .

Raspberry pi

source ~/.profile           #" loads virtual environment profile settings
workon cv                   #" opens virtual environment cv

# Install lxml
sudo apt install libxml2-dev libxslt-dev

# Only on Python 2 - you must install and link pyqt4
sudo apt install python-qt4

#: Replace ~/.virtualenvs/cv with venv/ on linux
ln -s /usr/lib/python2.7/dist-packages/PyQt4/ ~/.virtualenvs/cv/lib/python2.7/site-packages/
ln -s /usr/lib/python2.7/dist-packages/sip.so ~/.virtualenvs/cv/lib/python2.7/site-packages/

#: Install inkcut
pip install .

# On the raspberry pi, install RPI.GPIO (if using the motor control driver)
pip install RPi.GPIO

# Install zbar (pi only for crop mark registration)
pip install git+https://github.com/npinchot/zbar.git

Plugins

Inkcut is designed entirely using plugins using enaml's workbench framework. The inkcut source is separated into packages where each is a plugin (and any plugins that plugin adds).

The default plugins allow developers to define:

  • New dock items
  • Menu items and commands
  • Cli commands and hooks
  • New device drivers
  • Device protocols
  • Special connection types

These plugins can interact with all builtin plugins using the enaml workbench interface.

External plugins

You can define plugins and install them using python entry points. Inkcut loads external plugins from the inkcut.plugin entry point. Using this you can create python packages usesrs can install to extend Inkcut. The entry point implementation shall return an enaml PluginManifest factory (either the PluginManifest subclass or a function that when called returns a PluginManifest instance).

See a nice intro on entry points here using-plugins

Device extensions

Inkcut was redesigned to have separation between the device job processing, device connection, the protocol used, and the configuration of each. All of these can be completely customized as is needed for your specific hardware.

This extensibility should allow Inkcut to be used for more than vinyl cutters and plotters as discussed below.

Device drivers

Custom device "drivers" can be implemented to enable Inkcut to control specific device. A custom stepper motor driver for Inkcut using the raspberry pi demonstrates the usage of this. DeviceDrivers must implement the Device interface.

The driver may have it's own configuration and UI for editing the configuration without needing to modify any core functionality. Adding a driver is done by simply registering it with a plugin.

A driver may also transform, manipulate, and do any post processing of a path before it is sent to the device. The actual connecting, sending, and processing can all be overridden as is needed by the driver.

Protocols

If the builtin driver is sufficient for processing the job but uses a custom communication protocol. The custom protocol can be added as an external plugins or to the builtin device protocols (such as HPGL, DMPL, etc.. ) in the inkcut.device.protocols plugin. The protocol must implement the basic DeviceProtocol interface.

The protocol may have it's own configuration options and UI for editing the options without needing to modify any core functionality.

Connections

Connections (such as Serial port, Printer, etc.. ) are added in the inkcut.device.transports packages. Connections are simply an interface used to communicate with "some device".

Serial and printer connections are included by default. More can be added by external plugins. The plugin must implement the basic DeviceTransport interface.

Each connection may have it's own configuration and UI for editing the configuration without needing to modify any core functionality.

Filters

Filters are used to do preprocessing of the job before it is converted to commands to be sent to the device. Examples of filters are blade offset and overcut compensation.

New filters should be added to the inkcut.device.filters packages. Or they can be added by external plugins. The plugin must implement the basic DeviceFilter interface.

Filters are applied to the "path model" (QPainterPath) either before or after it is converted to a polygon for sending to the device.

Each filter may have it's own configuration and UI for editing the configuration without needing to modify any core functionality.

Jobs

Inkcut now uses the concept of a "Job" to represent an SVG graphic and the configuration settings required to create the final output. The core piece of this is the svg parser that generates a QPainterPath. The QPainterPath is used to internally represent the paths that must eventually be sent to the device.

Contributing

Contributions are welcome. Please document any enhancements using markdown. New pages can be added to the site.json in the docs folder and can link to markdown files. The project website updates it's cached pages after about an hour.

How to use markdown

See mastering-markdown

Pushing changes with git

Cd to the folder and

git add <file/path>
git commit -m "Some message"
git push origin master

#: Config is in .git/config

Releasing

Build:

rm -r dist
python setup.py sdist
python setup.py bdist_wheel --universal

To do a test release:

twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Then install and test it (on other machines) with:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple inkcut

To do the actual release:

twine upload dist/*

See also:

  • https://packaging.python.org/tutorials/distributing-packages/
  • https://packaging.python.org/guides/using-testpypi/#using-test-pypi

Donations

I put a lot of work into this project. Initial development started in 2015 and Inkcut was completely rewritten 4 times since then, improving every iteration. Please consider donating or sponsoring the development of Inkcut here.

See an error or is something missing? Suggest an edit on github