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:
   ```bash
   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:
```bash
python mac_ps_extract.py /path/to/psd_files
```

With options:
```bash
# 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:
```json
{
  "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:
```bash
python mac_ps_update.py /path/to/json_files
```

With options:
```bash
# 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:
```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