label_printer/documentation/QUICK_START.md

Quick Start Guide - PDF Label Printing System

Installation & Setup

1. Activate Virtual Environment

cd /srv/Label-design
source venv/bin/activate

2. Install Dependencies (One-time)

pip install -r requirements_gui.txt

Or manually:

pip install python-barcode pillow pycups kivy reportlab

Running the Application

GUI Application (Recommended for Users)

source venv/bin/activate
python label_printer_gui.py

The GUI will open with:

• Input fields for SAP number, quantity, and lot ID
• Real-time label preview
• Printer selection dropdown
• Print button for easy printing

Command Line (For Scripts/Integration)

source venv/bin/activate
python3 -c "from print_label import print_label_standalone; print_label_standalone('SAP-123|100|LOT-456', 'printer_name')"

Using the System

Basic PDF Label Generation

from print_label import create_label_pdf

# Generate PDF file
pdf_file = create_label_pdf("SAP-123|100|LOT-456")
print(f"Created: {pdf_file}")

Print to Printer

from print_label import print_label_standalone

# PDF (recommended - highest quality)
print_label_standalone("SAP-123|100|LOT-456", "printer_name", use_pdf=True)

# PNG (fallback)
print_label_standalone("SAP-123|100|LOT-456", "printer_name", use_pdf=False)

Advanced: Custom Label Size

from print_label_pdf import PDFLabelGenerator

# Create 6cm × 4cm labels at 600 DPI
generator = PDFLabelGenerator(label_width=6, label_height=4, dpi=600)
pdf = generator.create_label_pdf(
    sap_nr="SAP-123",
    cantitate="100",
    lot_number="LOT-456",
    filename="custom_label.pdf"
)

Key Features

PDF Generation (Default)

• Quality: Professional vector-based format
• File Size: ~1.7 KB per label (91% smaller than PNG)
• Scalability: Works at any print resolution
• Speed: 200-500ms per label
• Barcodes: Sharp, reliable Code128 barcodes

PNG Format (Fallback)

• Quality: Rasterized at 300 DPI
• Compatibility: Works with older systems
• File Size: ~19 KB per label
• Use Case: Legacy printer support

Finding Printer Name

To see available printers:

# Using CUPS
lpstat -p -d

# Or in Python
import cups
conn = cups.Connection()
printers = conn.getPrinters()
for name in printers.keys():
    print(name)

Generated Files

Labels are saved with timestamps:

• final_label_20260205_000537.pdf (timestamp format)
• Files are retained in current directory
• Easy to retrieve for reprinting

Format Options

Text Format: "SAP|QUANTITY|LOT"

"SAP-12345|100|LOT-ABC123"
     ↓        ↓     ↓
   SAP-Nr  Cantitate  Lot Nr

Each part becomes a barcode + label row in the output.

Troubleshooting

"No module named reportlab"

source venv/bin/activate
pip install reportlab

"No such file or directory" (printer error)

This is normal - it means the printer doesn't exist. Create a valid printer in CUPS first:

# Configure printer in CUPS web interface
http://localhost:631

GUI Won't Start

Make sure display is available:

# Check if X11 is running
echo $DISPLAY

Barcode Not Showing

The system falls back to text if barcode generation fails. Make sure:

• Value is under 25 characters
• Text contains valid barcode characters
• System has write access to temp directory

Testing

Run the comprehensive demo:

source venv/bin/activate
python demo_pdf_system.py

This tests:

• Basic PDF generation
• Custom dimensions
• Batch processing
• High DPI support
• PNG fallback
• API usage examples

File Structure

/srv/Label-design/
├── label_printer_gui.py      # GUI Application
├── print_label.py            # Main printing module (updated with PDF support)
├── print_label_pdf.py        # PDF generation engine
├── demo_pdf_system.py        # Comprehensive demo
├── requirements.txt          # Base dependencies
├── requirements_gui.txt      # GUI dependencies
├── PDF_UPGRADE_GUIDE.md      # Full documentation
├── TEST_RESULTS_PDF_SYSTEM.md # Test results
├── QUICK_START.md            # This file
└── venv/                     # Virtual environment

Performance

Task	Time	Notes
Single PDF generation	200-500ms	Per label
Single PNG generation	300-600ms	Legacy
Batch (4 labels)	~1.5 seconds	PDF format
Print submission	~100ms	To CUPS

Tips & Best Practices

1. Use PDF by default - Better quality, smaller files
2. Keep PNG option - For backward compatibility
3. Use 300 DPI - Standard for barcode scanning
4. Archive PDFs - Smaller file sizes = less storage
5. Test printer - Verify PDF support before large runs

Support Resources

• Full Documentation: See PDF_UPGRADE_GUIDE.md
• Test Results: See TEST_RESULTS_PDF_SYSTEM.md
• Demo Code: Run demo_pdf_system.py
• Code Examples: Look at function docstrings

Environment Variables

Optional environment customization:

# Set default printer
export CUPS_DEFAULT_PRINTER="your_printer_name"

# Set temp directory for label files
export TMPDIR="/path/to/temp"

---

Status: ✓ Production Ready
Last Updated: February 5, 2026
Version: 2.0 (PDF-based)