================================================================================
UPC-A (UPC-12) BARCODE GENERATOR FOR ADOBE ILLUSTRATOR
================================================================================

An Adobe Illustrator script (UPC12Barcode.jsx) that converts 12-digit text frames
into production-ready UPC-A barcodes.


FEATURES
================================================================================

Core Functionality
------------------
- Automatically finds and converts all 12-digit text frames in the active document
- Validates UPC-A checksums before conversion
- Maintains original text position and rotation
- Uses OCR-B Standard font for barcode numbers

Print Compensation
------------------
Bar Width Reduction (BWR) compensates for ink spread during printing.

⚠️ IMPORTANT: BWR values are printer-specific. The correct value depends on
your printer, substrate, ink, and press settings. Consult your printer for
their recommended BWR value.

Default: 0% (no reduction) - suitable for screen/online use and when
professional regeneration will occur

Barcode Height Control
----------------------
Two height modes for complete control over barcode dimensions:

Proportional mode (default):
- Height = Text Width / divisor
- Example: divisor 3.3 = height is ~30% of width
- Maintains consistent proportions as text width varies

Fixed mode:
- Set absolute height in document units (points, mm, etc.)
- Same height for all barcodes regardless of width
- Useful for standardized layouts

Linked Files Support
--------------------
Option to save barcodes as linked EPS files instead of embedded graphics:
- Reduces file size for documents with many barcodes
- Stores EPS files in Barcodes/ subfolder next to your document
- EPS files are always regenerated to reflect current settings
- Requires document to be saved before creating linked files

Additional Options
------------------
- Selection support: Process selected text frames only, or all text frames in document
- Convert text to outlines: Creates print-ready barcodes with outlined text (eliminates font dependencies)
- Quiet zone guides: Adds Illustrator guide objects showing exact GS1 113-module quiet zone boundaries
- Remove white background: Option to remove the white rectangle behind barcodes
- White rectangle margins: Adjustable margins (top, bottom, left, right) in document units
  - Chain options: Link all margins, link pairs (top/bottom, left/right), or set independently
  - Default: 0 (no margins)
- Smart first-run: Settings dialog appears automatically on first use, then accessible via Option/Alt key

GS1 Compliance (v2.3)
---------------------
All barcodes are GS1-compliant with intelligent width modes:

Auto-detect mode (default - recommended):
- Measures text frame width → calculates exact GS1 magnification → generates compliant barcode
- Barcode matches your text frame size exactly (when within 29.83-74.58mm range)
- Outside range: clamped to nearest valid size with summary notification
- Use case: Draw text at desired size → run script → get compliant barcode

Manual magnification mode:
- Select specific GS1 scale (80%-200%) from dropdown
- Barcode generated at exact standard size regardless of text frame
- Use case: Need specific GS1 percentage for production specs

Height compliance:
- Automatically enforces GS1 minimum height (~22.85mm at 100%)
- User can make taller via height controls
- Never generates too-short barcodes

UPC-A Specifications
--------------------
- Barcode dimensions comply with GS1 UPC-A standard
- Module width: 0.330mm at nominal size (100%)
- Total barcode structure: 113 modules (9 left quiet + 95 bars + 9 right quiet)
- Symmetric quiet zones: 9 modules left (9X), 9 modules right (9X) per GS1 UPC-A
- 12-digit code with checksum
- First and last digits scaled to 0.75x height


PRODUCTION USE VS. DESIGN USE
================================================================================

When This Script is Sufficient
-------------------------------
- Design mockups and presentations - Visual accuracy for client approval
- Internal comps and prototypes - Early-stage design validation
- Non-retail applications - Products not sold through standard retail channels

When Professional Regeneration is Recommended
----------------------------------------------
- Retail production - Supermarkets, department stores, logistics systems
- GS1 compliance verification - Official barcode quality requirements
- High-volume manufacturing - Professional prepress with verified BWR values
- Critical scanning environments - Where barcode failure has serious consequences

Recommendation: For production work, use GS1 Standard mode (default) to ensure
compliance. Professional printers will typically regenerate barcodes with their
verified BWR values regardless of your source file.


INSTALLATION
================================================================================

1. Install OCR-B Standard font on your system
2. Download UPC12Barcode.jsx script
3. Place in Illustrator Scripts folder:
   - Mac: /Applications/Adobe Illustrator [version]/Presets/[language]/Scripts/
   - Windows: C:\Program Files\Adobe\Adobe Illustrator [version]\Presets\[language]\Scripts\


USAGE
================================================================================

First Run
---------
1. Create text frames with valid 12-digit UPC codes
2. (Optional) Select specific text frames to process, or leave nothing selected to process all
3. Run the script: File > Scripts > UPC12Barcode
4. Settings dialog appears automatically on first use
5. Configure your preferences:
   - Width mode: Auto-detect (recommended) or Manual magnification
   - Manual magnification: 80%-200% (only when manual mode selected)
   - Bar Width Reduction (BWR): 0-20% - default 0%, printer-specific
   - Barcode height mode: Proportional or fixed
   - Options:
     - Save as linked EPS files (requires saved document)
     - Convert text to outlines (print-ready, no font dependencies)
     - Add quiet zone guides (shows GS1 boundaries)
     - Remove white background rectangle
   - White rectangle margins: Set top, bottom, left, right margins
     - Chain options: All, Pairs (T/B, L/R), or Independent
6. Click OK - settings are saved automatically

Width Modes Explained:
- Auto-detect (default): Barcode size = text frame size (when valid), always GS1-compliant
  - Text 40mm → Barcode 40mm at 107.27% magnification ✓
  - Text 25mm → Barcode 29.83mm at 80% (clamped to minimum) ⚠️
- Manual: Barcode size = selected magnification, ignores text frame
  - 100% = 37.29mm, 120% = 44.75mm, 200% = 74.58mm

Subsequent Runs
---------------
- Script uses your saved settings
- Barcodes are generated instantly
- Hold Option (Mac) or Alt (Windows) while running the script to change settings
- Selection support: Select specific text frames to convert only those, or run
  without selection to process all 12-digit text frames in the document

Tips
----
- Selection: Select text frames before running to process only those (otherwise processes all)
- Alert: If no valid 12-digit codes found, an alert displays with helpful instructions
- Text frames on locked or hidden layers are ignored
- Invalid checksums trigger a warning with the correct digit
- Barcode positioning: First digit of barcode aligns with original text anchor point
  (works with any text justification and rotation)
- For linked files: Document must be saved first; EPS files are always regenerated
  to reflect current settings
- Quiet zone guides: Show exact GS1 113-module boundaries, independent of white
  rectangle margins (which can be larger for production trim areas)


REQUIREMENTS
================================================================================

- Adobe Illustrator CS6 or later
- OCR-B Standard font installed
- Valid 12-digit UPC codes with correct checksums


TECHNICAL DETAILS
================================================================================

GS1 Standard Dimensions (UPC-A)
---------------------------------
Nominal size (100%): 37.29mm total width
- Bars width: 31.35mm (excluding quiet zones)
- Module width (X-dimension): 0.330mm
- Total modules: 113 (9 left quiet + 95 bars + 9 right quiet)
- Quiet zones: 2.97mm left (9X) + 2.97mm right (9X) - SYMMETRIC
- Allowed range: 80%-200% of nominal
  - Minimum: 25.08mm bars (29.83mm total) - smallest scannable size
  - Maximum: 62.70mm bars (74.58mm total) - largest compliant size

Common magnification levels:
- 80% (minimum): 25.08mm bars → 29.83mm total → 18.28mm min height
- 100% (nominal): 31.35mm bars → 37.29mm total → 22.85mm min height
- 120% (large): 37.62mm bars → 44.75mm total → 27.42mm min height
- 200% (maximum): 62.70mm bars → 74.58mm total → 45.70mm min height

Note: Height shown is GS1 minimum. Script automatically enforces this while
allowing taller barcodes.

Why standards matter: Retail logistics systems are calibrated for GS1 dimensions.
Non-compliant barcodes may scan with handheld devices but fail automated scanning
at supermarkets and distribution centers.

Barcode Width Modes
-------------------
Auto-detect mode (default):
- Calculates magnification from text frame width: magnification = (textWidth / 37.29) × 100
- Bars width = 31.35mm × (magnification/100)
- Total width includes scaled quiet zones (2.97mm left + 2.97mm right at 100%)
- Clamped to valid range if outside 80%-200%
- Recommended for all retail/production use
- Silent operation (no warnings when within range)

Manual magnification mode:
- User selects magnification (80%-200%) from dropdown
- Bars width = 31.35mm × (magnification/100)
- Text frame width ignored
- Use when specific GS1 percentage required for production specs

Barcode Height Modes
--------------------
- Proportional: Height = Width / divisor (default divisor: 3.3)
- Fixed: User-specified height in document units (minimum: 5 units)

Bar Width Reduction (BWR)
-------------------------
⚠️ IMPORTANT: BWR values are printer-specific guidelines, not absolute standards.

- Default: 0% (no reduction)
- Range: 0-20% (custom input)
- Printer dependency: The correct BWR value depends on your specific printer,
  substrate, ink, and press settings
- Professional workflow: Commercial printers typically regenerate barcodes with
  their own verified BWR values
- Recommendation: Consult your printer for the correct BWR value, or leave at 0% (default)

Technical details:
- Reduces black bars by specified percentage to compensate for ink spread (dot gain)
- Applied symmetrically to maintain barcode integrity
- Example: 5% BWR on a 0.330mm bar = 0.0165mm reduction per side (0.033mm total)

File Formats
------------
- Embedded: Vector paths in CMYK (100% black)
- Linked: EPS files with embedded fonts, CMYK, Illustrator 10 compatibility


TROUBLESHOOTING
================================================================================

"Barcode is not readable" error:
- Ensure you're using the latest version (v2.3) for GS1-compliant barcodes
- Use GS1 Standard mode (default) for production barcodes
- Verify text frame contains exactly 12 digits with valid checksum
- Consult your printer for appropriate BWR value if needed

"Font not available" error:
- Install OCR-B Standard font
- Restart Illustrator after font installation

"Document must be saved" dialog:
- Appears when linked files option is enabled
- Save document or uncheck "Save as linked EPS files" in settings

Barcodes too large/small:
- Auto-detect mode (default): Barcode matches text frame size (within valid range)
- Manual mode: Barcode size = selected magnification percentage
- Use width mode settings to control barcode width
- Use height mode settings to control barcode height

Settings dialog not appearing:
- On first run, dialog appears automatically
- After first run, hold Option/Alt while running the script
- To reset preferences, delete: ~/Library/Application Support/UPC12Barcode_BWR.txt (Mac)


VERSION HISTORY
================================================================================

v2.3 (2026) - Production Workflow Enhancements
-----------------------------------------------
- NEW: Selection support - process selected text frames or all text frames
- NEW: Convert text to outlines option - creates print-ready barcodes without font dependencies
- NEW: Quiet zone guides - adds guide objects showing exact GS1 113-module boundaries
- NEW: Margin chain options - link all margins, link pairs (top/bottom, left/right), or set independently
- NEW: Alert when no valid 12-digit codes found
- IMPROVED: Barcode positioning - first digit aligns with original text anchor point (works with rotated text)
- IMPROVED: Linked EPS files always regenerated to reflect current settings
- IMPROVED: Margin input UI - reorganized as top/bottom and left/right pairs with cleaner number formatting
- FIXED: Vertical alignment scales correctly with manual magnification
- FIXED: Fixed height mode now uses document units (mm/cm/in/pt/pc) instead of points for consistent UX
- FIXED: UPC-A quiet zones corrected to symmetric 9X+9X per GS1 specification

v1.0 (2021)
-----------
- Initial release
- Basic UPC-A barcode generation
- Checksum validation


LICENSE
================================================================================

Free for commercial and personal use.

Attribution: If you use this code or portions of it in your own projects,
please credit the original author:
"Based on UPC12Barcode.jsx by Katja Bjerrum (https://productivista.com)"


CREDITS
================================================================================

UPC12Barcode.jsx created by Katja Bjerrum / Productivista (https://productivista.com)

Specialized in Adobe Illustrator workflow automation for packaging, print,
and textile/fashion production teams.

For support, feature requests, or bug reports, please visit:
https://productivista.com
