df3tools 0.1.0
Tools to convert Pov-Ray DF3 files to set of images and vice versa
License: MIT
Keywords: povray pov-ray density file df3 commandline tools utils utility

========
df3tools
========

.. image:: https://travis-ci.org/a5kin/df3tools.png?branch=master
    :target: https://travis-ci.org/a5kin/df3tools?branch=master
    :alt: Build Status

.. image:: https://img.shields.io/codeclimate/coverage/github/a5kin/df3tools.svg
    :target: https://codeclimate.com/github/a5kin/df3tools
    :alt: Coverage Status

.. image:: https://img.shields.io/codeclimate/maintainability/a5kin/df3tools.svg
    :target: https://codeclimate.com/github/a5kin/df3tools
    :alt: Maintainability Status

.. image:: https://img.shields.io/scrutinizer/g/a5kin/df3tools.svg
    :target: https://scrutinizer-ci.com/g/a5kin/df3tools/
    :alt: Code Quality

.. image:: https://img.shields.io/pypi/v/df3tools.svg
    :target: https://pypi.org/project/df3tools/
    :alt: Latest PyPI version

.. image:: https://img.shields.io/pypi/pyversions/df3tools.svg
    :target: https://pypi.org/project/df3tools/
    :alt: Supported Python versions

Command-line tools to convert POV-Ray density files (DF3) to a bunch
of images and vice versa.

------------
Installation
------------

The easiest way to install is via standard Python package manager::

    pip install df3tools

Optionally, you may clone package's repository, and run ``setup.py``
script::

    git clone https://github.com/a5kin/df3tools.git
    cd df3tools
    python setup.py install

----------
Quickstart
----------

After successful installation, two tools will be available at
command-line: ``df3split`` and ``df3combine``.

The former, by default, splits density file to a bunch of images and
saves them into ``layerNNN.tga`` files in current directory::

    df3split path-to-original-density-file.df3

The latter, by default, combines all ``layer*`` files in current
directory into a single density file. Image format is auto-detected::

    df3combine path-to-new-density-file.df3

You may also pass an images' prefix like ``-p data/layer``. See the
full list of options below.

--------
df3split
--------

Split POV-Ray ``.df3`` density file to a series of separate images.

Usage
-----
::

    df3split [-h] [-t {tga,png}] [-p PREFIX] [-s] df3file


Positional arguments:
---------------------
::

    df3file    Filename of density file to split.

Optional arguments:
-------------------
::

    -h, --help                        Show help message and exit.
    -t {tga,png}, --format {tga,png}  Output files format.
    -p PREFIX, --prefix PREFIX        Output files prefix.
    -s, --silent                      Suppress output.

----------
df3combine
----------

Combine a series of separate images into POV-Ray ``.df3`` density file.

Usage:
------
::

    df3combine [-h] [-p PREFIX] [-s] df3file

Positional arguments:
---------------------
::

    df3file    Filename of density file to combine images into.

Optional arguments:
-------------------
::

    -h, --help                        Show help message and exit.
    -p PREFIX, --prefix PREFIX        Input files prefix.
    -s, --silent                      Suppress output.

Note, images format is autodetected. You may combine any type of
images, supported by Pillow.

-----
Tests
-----

To run full test suite for all supported Python versions, install
``tox`` package, and run it from project's top directory, containing
``setup.py``::

    pip install tox
    tox

Optionally, you can run tests only for your current Python version by
typing::

    python -m unittest discover -s tests

----------------
Acknowledgements
----------------

Thanks to *Yury Poberezhny* for the idea and motivation to create this
package.