adobe-ps-scripts-loreal/MAC-SCRIPTS.md

Mac Photoshop Script Documentation

This document provides detailed information on using the macOS-specific scripts for extracting and updating text in Photoshop files.

Overview

These scripts use AppleScript to control Photoshop directly on macOS, providing a reliable method for text layer manipulation:

1. mac_ps_extract.py: Extracts text from PSD files into JSON format
2. mac_ps_update.py: Updates text layers in PSD files using edited JSON

This approach offers several advantages over the Adobe Photoshop API:

• ✅ Reliable text updates that actually change the text content
• ✅ Works with all layer types and preserves text formatting
• ✅ No need for cloud storage or API credentials
• ✅ Direct integration with local Photoshop installation
• ✅ Faster processing time for batch operations

Requirements

• macOS (10.15 Catalina or later)
• Adobe Photoshop (2024, 2025, or later) installed locally
• Python 3.7 or higher

Installation

1. Clone the repository or download the scripts
2. Install dependencies:

   pip install -r requirements.txt
   

Text Extraction Process (mac_ps_extract.py)

How It Works

1. Photoshop Detection and Launch:

   • Automatically detects installed Photoshop versions
   • Launches Photoshop if not already running
   • Uses AppleScript to communicate with Photoshop

2. File Opening and Processing:

   • Opens each PSD file in Photoshop
   • Executes the ExtractTextWithBreaks.jsx script
   • Extracts all text layers with their formatting information

3. JSON Output Generation:

   • Creates a structured JSON file for each PSD
   • Preserves layer names, paths, and content
   • Maintains rich text formatting information
   • Names output files with -textonly.json suffix

Command-Line Usage

Basic usage:

python mac_ps_extract.py /path/to/psd_files

With options:

# Extract to a specific output directory
python mac_ps_extract.py /path/to/psd_files -o /path/to/output_dir

# Process PSD files in subdirectories
python mac_ps_extract.py /path/to/psd_files -r

# Enable verbose logging
python mac_ps_extract.py /path/to/psd_files -v

JSON Output Format

The generated JSON files include:

• Document metadata (name, dimensions)
• Complete list of text layers
• Text content and formatting for each layer
• Style information (font, size, formatting)

Example JSON structure:

{
  "documentName": "example.psd",
  "psdPath": "/path/to/example.psd",
  "extractedAt": "2025-04-22 14:32:27",
  "dimensions": {
    "width": 1200,
    "height": 800
  },
  "textLayerCount": 2,
  "textLayers": [
    {
      "id": "",
      "name": "Headline",
      "path": "Headline",
      "text": "Product Name",
      "updatedText": "Product Name",
      "visible": true,
      "styleInfo": {
        "font": "Arial-Bold",
        "size": 24,
        "color": null,
        "alignment": "left",
        "styles": [
          {
            "start": 0,
            "end": 12,
            "text": "Product Name",
            "font": "Arial-Bold",
            "style": "Bold",
            "size": 24
          }
        ]
      },
      "hasRichTextFormatting": false
    },
    {
      "id": "",
      "name": "Description",
      "path": "Text Group/Description",
      "text": "This is a product description.\nIt has multiple lines.\nBullet points:\n• Feature one\n• Feature two",
      "updatedText": "This is a product description.\nIt has multiple lines.\nBullet points:\n• Feature one\n• Feature two",
      "visible": true,
      "styleInfo": {
        "font": "Arial",
        "size": 12,
        "color": null,
        "alignment": "left",
        "styles": [
          {
            "start": 0,
            "end": 30,
            "text": "This is a product description.",
            "font": "Arial",
            "style": "Regular",
            "size": 12
          },
          {
            "start": 31,
            "end": 51,
            "text": "It has multiple lines.",
            "font": "Arial",
            "style": "Regular",
            "size": 12
          },
          {
            "start": 52,
            "end": 66,
            "text": "Bullet points:",
            "font": "Arial-Bold",
            "style": "Bold",
            "size": 12
          },
          {
            "start": 67,
            "end": 81,
            "text": "• Feature one",
            "font": "Arial",
            "style": "Regular",
            "size": 12
          },
          {
            "start": 82,
            "end": 96,
            "text": "• Feature two",
            "font": "Arial",
            "style": "Regular",
            "size": 12
          }
        ]
      },
      "hasRichTextFormatting": true
    }
  ]
}

Text Update Process (mac_ps_update.py)

How It Works

1. JSON and PSD File Matching:

   • Locates PSD files corresponding to JSON data
   • Uses smart matching based on filenames or metadata
   • Finds PSD files even with minor naming differences

2. Text Update Processing:

   • Opens the PSD file in Photoshop
   • Loads the JSON file with updated text
   • Executes the updateTextLayers.jsx script
   • Updates text while preserving formatting

3. Results and Verification:

   • Reports success/failure for each file processed
   • Provides detailed logs of changes made
   • Validates layer matches and text changes

Command-Line Usage

Basic usage:

python mac_ps_update.py /path/to/json_files

With options:

# Specify PSD files in a different directory
python mac_ps_update.py /path/to/json_files -p /path/to/psd_files

# Save changes to PSD files after updating
python mac_ps_update.py /path/to/json_files --save

# Dry run to preview changes without applying them
python mac_ps_update.py /path/to/json_files --dry-run

# Enable verbose logging
python mac_ps_update.py /path/to/json_files -v

JSON Editing Guidelines

When editing the JSON files:

1. Only modify the updatedText field for layers you want to change
2. Preserve line breaks using \n for proper formatting
3. Maintain the original JSON structure and field names
4. Do not remove or change layer IDs, names, or paths
5. Save in UTF-8 encoding to preserve special characters

Example of proper text update in JSON:

"textLayers": [
  {
    "name": "Headline",
    "text": "Original Product Name",
    "updatedText": "New Product Name",
    "visible": true,
    // other fields...
  }
]

Advanced Features

Rich Text Preservation

The scripts maintain text styling information for rich-formatted text:

• Multiple Paragraph Support: Preserves paragraph breaks and spacing
• Mixed Formatting: Maintains different styles within the same text layer
• Character-Level Styling: Preserves bold, italic, and other text attributes
• Bullet Points: Correctly handles bullet points and special characters

Batch Processing

Both scripts support efficient batch processing:

• Multiple File Handling: Process entire directories of files
• Recursive Search: Optionally find files in subdirectories
• Error Recovery: Continue processing even if some files fail
• Detailed Reporting: Generate summaries of successful and failed operations

Common Issues and Troubleshooting

Photoshop Launch Issues

Problem: Script fails to detect or launch Photoshop
Solution:

• Verify Photoshop is installed in the standard location
• Launch Photoshop manually first, then run the script
• Use the -v flag for verbose logging to diagnose issues

File Path Problems

Problem: Script can't find or open PSD/JSON files
Solution:

• Ensure filenames don't contain special characters
• Use absolute paths when specifying directories
• Check file permissions and ownership

Text Layer Matching Failures

Problem: Script can't find layers to update
Solution:

• Verify layer names match exactly between PSD and JSON
• Check if layers are inside groups (path differences)
• Try using the -v flag to see which layers are found

AppleScript Permissions

Problem: Permission errors when executing AppleScript
Solution:

• In System Preferences → Security & Privacy, allow script execution
• Grant terminal/script editor automation permissions for Photoshop
• Run from Terminal with full disk access

Performance Considerations

• Memory Usage: These scripts have minimal memory footprint
• Processing Time: Extracting text typically takes 5-10 seconds per PSD file
• Batch Efficiency: Processing multiple files is more efficient than individual runs
• Background Operation: Scripts can run in the background while you work on other tasks

Future Improvements

Planned enhancements to the scripts:

1. Font Validation: Check if specified fonts exist in the system
2. Layer Creation: Add ability to create new text layers
3. Multi-Document Processing: Process multiple PSD files simultaneously
4. Automation Scheduling: Set up automated batch processing at scheduled times
5. GUI Interface: Add a simple graphical interface for non-technical users