Metadata-Version: 2.4
Name: inventree-wireviz-plugin
Version: 1.3.0
Summary: Wireviz plugin for InvenTree
Home-page: https://github.com/inventree/inventree-wireviz
Author: Oliver Walters
Author-email: oliver.henry.walters@gmail.com
License: MIT
Keywords: inventree inventory wireviz wiring cable harness
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Framework :: InvenTree
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: wireviz>=0.4.1
Requires-Dist: pint>=0.24.4
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI](https://img.shields.io/pypi/v/inventree-wireviz-plugin)](https://pypi.org/project/inventree-wireviz-plugin/)
![CI](https://github.com/inventree/inventree-wireviz/actions/workflows/ci.yaml/badge.svg)

# inventree-wireviz

The **inventree-wireviz** plugin provides direct integration for [wireviz](https://github.com/formatc1702/WireViz), a text-based wiring harness specification tool.

## Functionality

The plugin provides a number of key functions:

### Harness Diagram Generation

This plugin provides server-side generation of a wiring harness diagram from a `.wireviz` file. Uploading a simple [harness file](./demo/harness.wireviz) results in the generation of a wiring diagram:

![](./demo/harness.svg)

> **Note**
> Refer to the [wireviz syntax guide](https://github.com/formatc1702/WireViz/blob/master/docs/syntax.md) for a full description of the file format.

The generated harness diagram is available as a `.svg` file.

### BOM Extraction

Bill of Materials (BOM) information can be extracted directly from the harness description file, allowing for a harness assembly to be fully qualified from the template file.

### Report Generation

The generated `.svg` can be used in report templates, for example as a reference diagram in a Build Order Report

## Installation

### Installation Requirements

You must have [graphviz](https://graphviz.org/) installed, and accessible by the InvenTree server.

e.g. `apt install graphviz`

If installing in a container environment (e.g. Docker), the dockerfile will need to be extended to install the *graphviz* binaries

### Plugin Installation

The plugin is available [via PIP](https://pypi.org/project/inventree-wireviz-plugin/). Follow the [InvenTree plugin installation guide](https://docs.inventree.org/en/latest/plugins/install/) to install the plugin on your system

### Configuration

Once the plugin is installed, it needs to be enabled before it is available for use. Again, refer to the InvenTree docs for instructions on how to enable the plugin. After the plugin is enabled, the following configuration options are available:

![](./docs/config.png)

| Setting | Description |
| --- | --- |
| Category Parameter | A category parameter template (scoped to part categories) whose value determines whether the Harness Diagram panel is shown. See [Category Parameter](#category-parameter) below. |
| Wire Harness Viewers | User group whose members are allowed to *view* harness diagrams. If unset, all users may view. |
| Wire Harness Editors | User group whose members are allowed to *upload/edit* harness diagrams. If unset, all users may edit. |
| Delete Old Files | Remove old harness diagram files when a new `.wireviz` file is uploaded |
| Extract BOM Data | Extract BOM data from harness file and generate new BOM entries |
| Clear BOM Data | Remove existing BOM entries first, before creating new ones |

#### Category Parameter

The **Category Parameter** setting controls which parts automatically show the Harness Diagram panel, without requiring a wireviz file to already be attached.

1. Create a *Parameter Template* in InvenTree that is scoped to **Part Categories** (e.g. `Is Wire Harness`).
2. Select that template in the **Category Parameter** plugin setting.
3. On any Part Category that represents a wire harness assembly, add that parameter and set its value to `true` or `yes`.

When a user opens a Part whose category (or any ancestor category) has this parameter set to `true`/`yes`, the Harness Diagram panel is displayed — even before a `.wireviz` file has been uploaded. This lets users upload a diagram directly from the panel rather than having to attach the file first.

> **Note**
> The check walks up the full category hierarchy, so setting the parameter on a parent category is inherited by all child categories.

Additionally, you must ensure that the following plugin features are enabled on the InvenTree server:

- Enable interface integration
- Enable URL integration
- Enable report integration

![](./docs/event_plugin.png)

## Operation

### Uploading Wireviz File

To generate a wiring harness diagram for a specific Part, upload a (valid) wireviz yaml file. The file **must** have the `.wireviz` extension to be recognized by the plugin.

> **Note**
> The Part must be marked as an **assembly** in InvenTree for the Harness Diagram panel to be displayed.

When the file is uploaded to the server, the plugin is notified and begins the process of generating the harness diagram. If successful, a `.svg` file is attached to the part instance:

![](./docs/svg_file.png)

### Harness Diagram Panel

When a Part has a valid harness diagram (i.e. generated without any critical errors), the *Harness Diagram* panel will be available for that part. This panel displays the diagram image, and a simple Bill of Materials (as defined in the uploaded `.wireviz` file):

![](./docs/harness_panel.png)

The panel is also displayed on the **Build Order** page for any build whose part has a harness diagram. On a build order the panel is read-only — uploading or deleting the diagram must be done from the Part page.

> **Note**
> You may need to reload the page before this panel is visible

> **Warning**
> Any warnings or errors which were raised during the process will be displayed here

### Dashboard Item

Users who have edit permission see a **Create Wireviz Diagram** item on the InvenTree dashboard. This provides a quick shortcut for starting a new harness without first navigating to a specific Part.

### BOM Extraction

If enabled, the plugin will attempt to generate a linked Bill of Materials based on the data provided in the file. The plugin tries several strategies to match each BOM line item to an existing InvenTree part, in the following order:

1. `pn` → part IPN
2. `pn` → part name
3. `description` → part description
4. `mpn` → manufacturer part MPN
5. `spn` → supplier part SKU
6. For wire entries (description starting with `Wire,`), the wire color suffix is appended to the `pn` and the IPN/name lookup is retried (e.g. `26AWG-PTFE` → `26AWG-PTFE-YE` for a yellow wire)

If a matching part is not found for a line item, this is marked with a warning in the simplified BOM table in the [harness diagram panel](#harness-diagram-panel).

### Reports

The generated diagram can be used in certain reports (such as the Build Order Report). If a wiring harness diagram is available for a Part, the following variables are injected into the report context:

| Variable | Description |
| --- | --- |
| `wireviz_svg_file` | Filename of the generated `.svg` image |
| `wireviz_bom_data` | List of BOM line items extracted from the harness file |

> **Note**
> `wireviz_svg_file` refers to the *filename* of the `.svg` image — not the file itself.
> Use the `{% encode_svg_image %}` template tag to render the image.

A very simple example is shown below:

```html
{% extends "report/inventree_build_order_base.html" %}

{% load report %}

{% block style %}
{{ block.super }}

.harness {
    border: 1px solid #AAA; 
    width: 100%;
    display: inline-block;
}

{% endblock %}

{% block page_content %}

{{ block.super }}

{% if wireviz_svg_file %}

    <h4>Harness Drawing</h4>
    <img class='harness' src='{% encode_svg_image wireviz_svg_file %}'>
{% endif %}

{% endblock page_content %}
```

The resulting report is rendered as below:

![](./docs/report.png)

## Wireviz Documentation

Documentation on the capabilities of wireviz itself:

- https://github.com/formatc1702/WireViz/blob/master/docs/README.md
- https://github.com/formatc1702/WireViz/blob/master/docs/syntax.md
