.. module:: ezdxf.addons.hpgl2.api

HPGL/2 Converter Add-on
=======================

.. versionadded:: 1.1

The :mod:`hpgl2` add-on provides tools to process and convert HPGL/2 plot files.

What are HPGL/2 Plot Files?
---------------------------

The Hewlett-Packard Graphics Language (HPGL) is a vector graphics language originally
developed by Hewlett-Packard in the 1970s. HPGL is widely used for controlling pen
plotters and other output devices, and it has become a de facto standard for
communicating between computers and output devices in the field of computer-aided design
(CAD) and drafting.

HPGL is a command-driven language that consists of a series of commands that control the
movement of the plotter pen, the selection of pens and other output parameters, and the
drawing of geometric shapes such as lines, arcs, circles, and text. The language is
interpreted by the plotter or other output device and translated into physical pen
movements on the drawing surface.

HPGL has evolved over the years, and various extensions have been added to support more
complex graphics operations and to improve compatibility with other graphics languages.
Despite the development of newer graphics languages and file formats, HPGL remains a
widely used format for vector-based graphics, particularly in the engineering and
architectural fields.

The Goal of This Add-on
-----------------------

An HPGL/2 plot file contains all of the data generated by a CAD application that has been
sent to a plotter to print an engineering drawing. In the past, the only way to access
this data was to view it on a plotter or an specialized application, which could be
expensive and impractical for many people. However, this module provides functions and
classes to convert HPGL/2 plot files into modern vector graphic formats such as `PDF`_
and `SVG`_ and of course DXF, allowing the data to be viewed and processed using a wide
range of software tools.

.. Important::

    The Python module PyMuPDF is required for the PDF export: https://pypi.org/project/PyMuPDF/

The :class:`Plotter` class in the :mod:`hpgl2` add-on supports only the most commonly
used commands of HPGL/2. This is because many CAD applications use only a small subset
of HPGL/2 to create their output, typically consisting of polylines and filled polygons.
For more information on the supported commands, please refer to the documentation for
the :class:`Plotter` class.

To use the HPGL2 add-on, the entry point is the :mod:`ezdxf.addons.hpgl2.api` module.
This module contains the public interface of the add-on and should be imported in the
following way:


.. code-block:: Python

    from ezdxf.addons.hpgl2 import api as hpgl2

    with open("hpgl2.plt", "rb") as fp:
        data = fp.read()
    doc = hpgl2.to_dxf(data, color_mode=hpgl2.ColorMode.ACI)
    doc.saveas("hpgl2_as.dxf")


High Level Functions
--------------------

.. autosummary::
    :nosignatures:

    to_dxf
    to_svg
    to_pdf
    to_pixmap

.. autofunction:: to_dxf

.. autofunction:: to_svg

.. autofunction:: to_pdf

.. autofunction:: to_pixmap

.. class:: ColorMode

    The color mode controls how color values are assigned to DXF entities

    .. attribute:: ACI

        Use the pen number as :ref:`ACI` for DXF entities, ignores the RGB color values

    .. attribute:: RGB

        Use the pen number as :ref:`ACI` but also set the RGB color for DXF entities,
        RGB color values have always higher priority than the ACI when displaying DXF
        content.

.. class:: MergeControl

    Merge control enumeration.

    .. attribute:: NONE

        export filled polygons in print order

    .. attribute:: LUMINANCE

        sort filled polygons by luminance

    .. attribute:: AUTO

        guess best order of filled polygons

The Low Level Functions and Classes
-----------------------------------

.. autofunction:: hpgl2_commands

The HPGL/2 commands are often mixed with the Printer Command Language (`PCL`_) and/or the
Raster Transfer Language (`RTL`_) commands in a single plot file.

Some plot files that contain pure HPGL/2 code do not contain the escape sequence
"Enter HPGL/2 mode", without this sequence the HPGL/2 parser cannot recognize the
beginning of the HPGL/2 code. Add the :attr:`ENTER_HPGL2_MODE` sequence in front of the
bytes stream to switch on the HPGL/2 manually, regardless of whether the file is an
HPGL/2 plot file or not, so be careful:

.. code-block:: Python

    commands = hpgl2_commands(hpgl2.ENTER_HPGL2_MODE + data)


.. autoclass:: Interpreter

    .. attribute:: errors

        List of error messages occurred during the interpretation of the HPGL/2 commands.

    .. attribute:: not_implemented_commands

        List of all unsupported/ignored commands from the input stream.

    .. automethod:: run

    .. automethod:: disable_commands

.. autoclass:: Plotter

Recorder
--------

.. autoclass:: Recorder

    .. automethod:: player

    .. automethod:: draw_polyline

    .. automethod:: draw_paths

Player
------

.. autoclass:: Player

    .. automethod:: copy

    .. automethod:: recordings

    .. automethod:: replay

    .. automethod:: bbox

    .. automethod:: transform

    .. automethod:: sort_filled_paths

Properties
----------

.. autoclass:: ezdxf.addons.hpgl2.properties.Properties

    .. attribute:: pen_index

        pen index as int

    .. attribute:: pen_color

        pen color as :class:`RGB` tuple

    .. attribute:: pen_width

        pen width in millimeters (float)

    .. attribute:: fill_type

        :class:`FillType` of filled polygons

    .. attribute:: fill_method

        :class:`FillMethod` of filled polygons

    .. attribute:: fill_hatch_line_angle

        fill hatch line angle in degrees

    .. attribute:: fill_hatch_line_spacing

        fill hatch line distance in plotter units

    .. attribute:: fill_shading_density

        fill shading density in percent from 0 to 100.

    .. automethod:: resolve_pen_color

    .. automethod:: resolve_fill_color

.. autoclass:: ezdxf.addons.hpgl2.properties.FillType

    .. attribute:: NONE

    .. attribute:: SOLID

    .. attribute:: HATCHING

    .. attribute:: CROSS_HATCHING

    .. attribute:: SHADING

.. autoclass:: ezdxf.addons.hpgl2.properties.FillMethod

    .. attribute:: EVEN_ODD

    .. attribute:: NONE_ZERO_WINDING

Exceptions
-----------

.. autoclass:: Hpgl2Error

.. autoclass:: Hpgl2DataNotFound

.. autoclass:: EmptyDrawing


.. _PyMuPDF: https://pypi.org/project/PyMuPDF/
.. _HPGL/2: https://en.wikipedia.org/wiki/HP-GL
.. _PCL: https://en.wikipedia.org/wiki/Printer_Command_Language
.. _RTL: https://en.wikipedia.org/wiki/Hewlett-Packard_Raster_Transfer_Language
.. _SVG: https://en.wikipedia.org/wiki/SVG
.. _PDF: https://en.wikipedia.org/wiki/PDF
