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

# Adobe Photoshop Text Extraction Scripts for macOS

This repository contains Python and JavaScript scripts specifically optimized for macOS to extract text from Adobe Photoshop PSD files without requiring any Windows-based dependencies.

## Overview

The scripts provide a way to automatically extract text layers from PSD files, preserving all formatting, line breaks, and styles. They're designed to work with:

- Adobe Photoshop on macOS (2024/2025/CC versions)
- Python 3.x
- Files with spaces in their names
- Batch processing of many PSD files
- Support for files with or without text layers

## Requirements

- macOS (tested on 10.15 and later)
- Adobe Photoshop (installed in the Applications folder)
- Python 3.6 or later

## Installation

### Option 1: Use with system Python

1. Clone or download this repository
2. Ensure you have Python 3.x installed on your Mac (verify with `python3 --version`)
3. No additional packages needed - the scripts use only standard library modules

### Option 2: Create a virtual environment (recommended)

```bash
# Navigate to the script directory
cd /path/to/Adobe-PS-scripts

# Create a virtual environment
python3 -m venv ./venv

# Activate the virtual environment
source ./venv/bin/activate

# When finished, deactivate the environment
deactivate
```

## Script Files

The package includes these main files:

- `mac_ps_extract.py` - The main Python script for extracting text from PSD files
- `ExtractTextWithBreaks.jsx` - The JavaScript (ExtendScript) code that runs within Photoshop
- `batch_extract_text.py` - A helper script for batch processing (optional)

## Usage

### Basic Usage

The simplest way to extract text from PSD files:

```bash
python3 mac_ps_extract.py /path/to/psd_files
```

This will:
1. Process all PSD files in the specified directory
2. Save JSON files with extracted text next to each PSD file
3. Naming format will be: `[original-filename]-textonly.json`

### Advanced Options

```bash
python3 mac_ps_extract.py /path/to/psd_files --output-dir /path/for/output --recursive --verbose
```

#### Command Line Arguments

| Argument | Short | Description |
|----------|-------|-------------|
| `--output-dir` | `-o` | Directory to save extracted JSON files (defaults to same as PSD) |
| `--recursive` | `-r` | Search for PSD files in subdirectories |
| `--verbose` | `-v` | Enable detailed logging for troubleshooting |

### Examples

**Extract text from all PSD files in the current directory:**
```bash
python3 mac_ps_extract.py .
```

**Extract text from a specific directory and save to another location:**
```bash
python3 mac_ps_extract.py /Users/username/Desktop/PSD_Files -o /Users/username/Desktop/Extracted_Text
```

**Process files recursively with verbose logging:**
```bash
python3 mac_ps_extract.py /Users/username/Projects/Assets -r -v
```

## Output Format

The script produces JSON files with this structure:

```json
{
  "documentName": "example.psd",
  "psdPath": "/path/to/example.psd",
  "extractedAt": "2025-03-18 09:00:00",
  "dimensions": {
    "width": 1920,
    "height": 1080
  },
  "textLayerCount": 2,
  "textLayers": [
    {
      "id": "",
      "name": "Heading",
      "path": "Heading",
      "text": "This is a heading",
      "updatedText": "This is a heading",
      "visible": true,
      "styleInfo": {
        "font": "Arial-Bold",
        "size": 24,
        "color": null,
        "alignment": "left",
        "styles": [
          {
            "start": 0,
            "end": 16,
            "text": "This is a heading",
            "font": "Arial-Bold",
            "style": "Bold",
            "size": 24
          }
        ]
      },
      "hasRichTextFormatting": false
    },
    // Additional text layers...
  ]
}
```

If a PSD file contains no text layers, an empty JSON file is still created with basic document information.

## How It Works

The system uses a combination of:

1. **AppleScript** to communicate with Adobe Photoshop
2. **ExtendScript** (JSX) to execute code inside Photoshop
3. **Python** to coordinate the process and handle file operations

The process flow is:
1. Python script locates PSD files to process
2. For each file, it uses AppleScript to open the PSD in Photoshop
3. It then runs the JSX script inside Photoshop to extract text
4. The extracted text is saved as a JSON file
5. Photoshop closes the document and moves to the next file

## Troubleshooting

### Common Issues

**Script fails to find Photoshop:**
- Ensure Photoshop is installed in the Applications folder
- The script looks for common Photoshop versions; you may need to update the `_find_photoshop` method if you have a different version

**Error opening files with spaces:**
- The script handles spaces in filenames, but if you're having trouble, avoid spaces in file/folder names

**No text extracted:**
- Some PSD files may not contain any text layers
- The script will create an empty JSON file with document info

**Script is taking too long:**
- Processing large PSD files can be time-consuming
- Try processing fewer files at once

### Verbose Logging

Run with the `-v` or `--verbose` flag to see detailed logs:

```bash
python3 mac_ps_extract.py /path/to/psd_files -v
```

The logs show:
- Photoshop detection and communication
- File opening and processing steps
- Text extraction details
- Error messages and warnings

## Limitations

- Works only on macOS with Photoshop installed
- Requires Photoshop to be closed or not actively editing files being processed
- Does not support modification of text layers (extraction only)
- Large files with many text layers can take time to process

## Advanced Customization

If you need to modify how text is extracted, you can edit:

- `ExtractTextWithBreaks.jsx` to change how text and formatting is extracted from Photoshop
- `mac_ps_extract.py` to modify file handling, AppleScript communication, or output format

## License

This project is available under the MIT License.

## Credits

Developed for efficient text extraction from Adobe Photoshop files on macOS, with special focus on handling multilingual text content and preserving formatting.

## Questions and Support

For issues, questions, or contributions:

1. Check the detailed logs with verbose mode (`-v`) to identify the issue
2. Ensure you're using a supported Photoshop version
3. Create an issue in the repository with:
   - Your macOS version
   - Your Photoshop version
   - Command you ran
   - Any error messages from verbose output