dvi3v - Object to SVG Extraction Tool
======================================

VERSION: 3.1.4.build (build = SVN revision)
LICENSE: GNU GPL v3
AUTHOR: Peter Felecan

VERSIONING SCHEME
-----------------
Four-digit Dewey decimal notation: major.minor.sequence.build

- major:    Incremented on major changes
- minor:    Incremented on minor changes
- sequence: Incremented at each delivery iteration
- build:    Auto-generated from SVN $Revision$ keyword

Example: VERSION file contains "3.1.16", SVN expands to "3.1.16.42"

DESCRIPTION
-----------
dvi3v extracts objects from photographs and generates filled SVG files with
real-world dimensions, using A4 paper (210×297mm) as dimensional reference.

FEATURES
--------
* Center-focused object detection
* A4 paper automatic detection for scale calculation
* Real-world dimensions in millimeters
* Works with realistic photography conditions
* Adjustable hole filling (50-150% strength)
* Color support (names and hex codes)
* Debug mode with intermediate images

REQUIREMENTS
------------
* bash
* ImageMagick (convert, identify)
* potrace
* bc

INSTALLATION
------------
From distribution tarball (recommended for users):

    tar xJf dvi3v-3.1.4.build.tar.xz
    cd dvi3v-3.1.4
    ./configure
    make
    make install

From source repository (for developers/packagers):

    # Bootstrap autotools (generates configure script)
    autoreconf --install --symlink
    
    # Then standard build
    ./configure
    make
    make install

Optional: Build PDF documentation (requires Emacs + TexLive):

    make check-doc-tools  # Verify tools available
    make pdf              # Build all PDF docs (calls pdf-local)

USAGE
-----
Basic usage:

    dvi3v photo.jpg output.svg

Auto-threshold with adjustment:

    dvi3v -a 7 photo.jpg output.svg

Adjustable hole filling:

    dvi3v -a 7 -n 120 photo.jpg output.svg

Custom color and margin:

    dvi3v -c red -m 3.0 photo.jpg output.svg

See man page for complete documentation:

    man dvi3v

DOCUMENTATION
-------------
* Concept.org - Project concept and design
* ResearchJournal.org - Development history
* FutureResearch.org - Future research topics
* DevelopmentStandard.org - Coding standards
* dvi3v.1 - Manual page

PROJECT STRUCTURE
-----------------
The project follows GNU coding standards and uses autotools for build
and distribution management.

Software:
  dvi3v          - Object extraction and SVG generation tool
  dvi3v.1        - Manual page

Hardware:
  hardware/      - OpenSCAD designs for camera stand
                   (adjustable height, A4 paper reference frame)

For more information, see the documentation files included in the
distribution.

REPORTING BUGS
--------------
Report bugs to: pfelecan@gmail.com

COPYRIGHT
---------
Copyright (C) 2026 Peter Felecan

This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Bug Reporting and Feedback
---------------------------
If you encounter issues:

Software Issues (dvi3v script):
  Run with debug: ./dvi3v -d input.jpg output.svg
  Check debug images in temporary directory
  Note system details (ImageMagick, potrace versions)
  
  For detailed instructions on which debug files to upload and why,
  see DebugFileUpload.org

Hardware Issues (3D printed jig):
  Note which component has issues
  Measure critical dimensions with calipers
  Note printer model and settings

Include in reports:
  - Version number (./dvi3v --version or VERSION file)
  - Complete command line used
  - Expected vs actual results

Contact: pfelecan@gmail.com
