# EAN-13 Barcode Generator for Adobe Illustrator

An Adobe Illustrator script (`EAN13.jsx`) that converts 13-digit text frames into production-ready EAN-13 barcodes.

## Features

### Core Functionality
- Automatically finds and converts all 13-digit text frames in the active document
- Validates EAN-13 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)
- **Quiet zone indicator:** Optional ">" symbol marking the end of the right quiet zone
- **Smart first-run:** Settings dialog appears automatically on first use, then accessible via Option/Alt key

### GS1 Compliance (v2.2)
**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

### ISO/IEC 15420 Compliance
- Barcode dimensions comply with **ISO/IEC 15420** standard
- Module width: 0.33mm at nominal size (100%)
- Total barcode structure: 113 modules (11 left quiet + 95 bars + 7 right quiet)
- Proper quiet zones: 11 modules left (11X), 7 modules right (7X) per ISO/IEC 15420

## 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

**Real-world example:** A packaging designer reported that barcodes generated with this script (using custom sizes and unverified BWR) scanned perfectly with handheld scanners but were rejected by a major Australian supermarket chain during GS1 compliance verification. The barcodes had to be professionally regenerated at the prepress stage.

**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 `EAN13.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 13-digit EAN-13 codes
2. **(Optional)** Select specific text frames to process, or leave nothing selected to process all
3. Run the script: `File > Scripts > EAN13`
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)
     - Add quiet zone indicator (> symbol)
     - 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 13-digit text frames in the document

### Tips
- **Selection:** Select text frames before running to process only those (otherwise processes all)
- **Alert:** If no valid 13-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 13-digit EAN-13 codes with correct checksums

## Technical Details

### GS1 Standard Dimensions
**Nominal size (100%):** 37.29mm total width
- **Bars width:** 31.35mm (excluding quiet zones)
- **Module width (X-dimension):** 0.33mm
- **Total modules:** 113 (11 left quiet + 95 bars + 7 right quiet)
- **Quiet zones:** 3.63mm left (11X) + 2.31mm right (7X)
- **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 (3.63mm left + 2.31mm 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.33mm 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.1) for GS1-compliant barcodes
- Use GS1 Standard mode (default) for production barcodes
- Verify text frame contains exactly 13 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:**
- **GS1 mode (default):** Barcode width = 37.29mm regardless of text frame size
- **Custom mode:** Barcode width = text frame width
- Uncheck "Use GS1 Standard width" in settings to use text frame 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/EAN13_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 13-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
- **IMPROVED:** Dialog labels fixed - "Scale" and "Chain" display correctly
- **FIXED:** Vertical alignment scales correctly with manual magnification

### v2.2 (2025) - Auto-Detect GS1 Width
- **NEW:** Auto-detect mode - calculates GS1 magnification from text frame width (default)
- **NEW:** Manual magnification mode - select specific GS1 scale from dropdown
- **NEW:** Automatic GS1 minimum height enforcement (~22.85mm at 100%)
- **NEW:** Smart height calculation - never generates too-short barcodes
- **NEW:** Summary notification when barcodes clamped to valid range
- **IMPROVED:** All barcodes always GS1-compliant (no custom mode)
- **IMPROVED:** Width modes via radio buttons (auto/manual)
- **CHANGED:** Preference file structure (lines 11-12: widthMode, manualMagnification)
- **REMOVED:** GS1 checkbox (replaced with width mode selection)
- **REMOVED:** Custom width mode with validation warnings

### v2.1 (2025) - GS1 Compliance Foundation
- **NEW:** GS1 Standard mode with checkbox and manual magnification
- **NEW:** Width validation against GS1 standard (29.83-74.58mm range)
- **NEW:** Unit conversion utilities (points ↔ millimeters)
- **NEW:** Production use guidelines in documentation
- **IMPROVED:** BWR simplified to custom input only (removed presets)
- **IMPROVED:** Settings dialog restructured with Options panel

### v2.0 (2025)
- **FIXED:** Barcode width now uses actual text frame width (not font size calculation)
- **FIXED:** Module width calculation for ISO/IEC 15420 compliance
- **FIXED:** Quiet zones now comply with ISO/IEC 15420 (11 modules left, 7 modules right)
- **FIXED:** White rectangle removal correctly identifies by CMYK values
- **NEW:** Dual height modes - proportional (Width/divisor) or fixed (document units)
- **NEW:** Bar Width Reduction (BWR) compensation for print processes
- **NEW:** White rectangle margins (top, left, right, bottom) separately adjustable - default: 3pt all sides
- **NEW:** Quiet zone indicator option ("> symbol marking right quiet zone)
- **NEW:** Linked EPS file export option with smart folder management
- **NEW:** Remove white background rectangle option
- **NEW:** Settings dialog with persistent preferences
- **NEW:** First-run dialog appears automatically, then accessible via Option/Alt key
- **NEW:** Improved dialog UI with framed panels and better spacing

### v1.0 (2022)
- Initial release
- Basic EAN-13 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 EAN13.jsx by Katja Bjerrum (https://productivista.com)"

## Credits

**EAN13.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 [productivista.com](https://productivista.com)
