feat(examples): enhance documentation and examples for Photoshop scri…

…pting

Update examples and documentation to provide clearer guidance on working with Photoshop layers, colors, and tools. Improve readability and add key concepts for better understanding.

Signed-off-by: longhao <[email protected]>

.flake8

@@ -1,34 +1,36 @@
-[flake8]
-ignore = BLK100
-
-# flake8-quotes:
-# Use double quotes as our default to comply with black, we like it and
-# don't want to use single quotes anymore.
-# We would love to configure this via our pyproject.toml but flake8-3.8 does
-# not support it yet.
-inline-quotes = double
-multiline-quotes = double
-docstring-quotes = double
-avoid-escape = True
-
-# flake8-docstrings
-# Use the Google Python Styleguide Docstring format.
-docstring-convention=google
-
-exclude =
-    # No need to traverse our git directory
-    .git,
-    # There's no value in checking cache directories
-    __pycache__,
-    # The conf file is mostly autogenerated, ignore it
-    docs/source/conf.py,
-    # The old directory contains Flake8 2.0
-    old,
-    # This contains our built documentation
-    build,
-    # This contains builds of flake8 that we don't want to check
-    dist,
-    venv,
-    docs
-
-max-line-length = 120
+[flake8]
+ignore = BLK100
+
+# flake8-quotes:
+# Use double quotes as our default to comply with black, we like it and
+# don't want to use single quotes anymore.
+# We would love to configure this via our pyproject.toml but flake8-3.8 does
+# not support it yet.
+inline-quotes = double
+multiline-quotes = double
+docstring-quotes = double
+avoid-escape = True
+
+# flake8-docstrings
+# Use the Google Python Styleguide Docstring format.
+docstring-convention=google
+
+exclude =
+    # No need to traverse our git directory
+    .git,
+    # There's no value in checking cache directories
+    __pycache__,
+    # The conf file is mostly autogenerated, ignore it
+    docs/source/conf.py,
+    # The old directory contains Flake8 2.0
+    old,
+    # This contains our built documentation
+    build,
+    # This contains builds of flake8 that we don't want to check
+    dist,
+    venv,
+    docs
+    examples
+    test
+
+max-line-length = 120

examples/active_layer.py

@@ -1,20 +1,36 @@
-# Set the active layer to the last art layer of the active document, or the
-# first if the last is already active.
+"""Example of working with active layers in Photoshop.
+
+This example demonstrates how to:
+1. Get and set the active layer in a document
+2. Create new art layers
+3. Manage layer names and properties
+
+The script will:
+- Create a new document if none exists
+- Add a new art layer if document has less than 2 layers
+- Display the current active layer name
+- Create a new layer and rename it
+"""
 
 # Import local modules
 from photoshop import Session
 
 
 with Session() as ps:
+    # Get or create a document
     if len(ps.app.documents) < 1:
         docRef = ps.app.documents.add()
     else:
         docRef = ps.app.activeDocument
 
+    # Ensure we have at least 2 layers
     if len(docRef.layers) < 2:
         docRef.artLayers.add()
 
+    # Display current active layer name
     ps.echo(docRef.activeLayer.name)
+
+    # Create and rename a new layer
     new_layer = docRef.artLayers.add()
     ps.echo(new_layer.name)
     new_layer.name = "test"

examples/apply_filters.py

@@ -1,61 +1,50 @@
+"""Example of applying various filters to layers in Photoshop.
+
+This example demonstrates how to:
+1. Apply different types of Photoshop filters
+2. Configure filter parameters
+3. Work with filter options
+4. Handle filter application to different layer types
+
+Key concepts:
+- Filter types and options
+- Layer filtering
+- Parameter configuration
+- Filter effects management
 """
-References:
-    https://github.com/lohriialo/photoshop-scripting-python/blob/master/ApplyFilters.py
-
-"""
-# Import third-party modules
-import examples._psd_files as psd  # Import from examples.
 
 # Import local modules
-# selections in the open document.
-import photoshop.api as ps
-
-
-PSD_FILE = psd.get_psd_files()
-
-# Start up Photoshop application
-app = ps.Application()
-
-# We don't want any Photoshop dialogs displayed during automated execution
-app.displayDialogs = ps.DialogModes.DisplayNoDialogs
-
-psPixels = 1
-start_ruler_units = app.preferences.rulerUnits
-if start_ruler_units is not psPixels:
-    app.preferences.rulerUnits = psPixels
-
-fileName = PSD_FILE["layer_comps.psd"]
-docRef = app.open(fileName)
-nLayerSets = len(list((i, x) for i, x in enumerate(docRef.layerSets))) - 1
-nArtLayers = len(
-    list((i, x) for i, x in enumerate(docRef.layerSets[nLayerSets].artLayers)),
-)
-
-active_layer = docRef.activeLayer = docRef.layerSets[nLayerSets].artLayers[nArtLayers]
-sel_area = ((0, 212), (300, 212), (300, 300), (0, 300))
-docRef.selection.select(sel_area, ps.SelectionType.ReplaceSelection, 20, True)
-print(f"Current active layer: {active_layer.name}")
-active_layer.applyAddNoise(15, ps.NoiseDistribution.GaussianNoise, False)
-
-backColor = ps.SolidColor()
-backColor.hsb.hue = 0
-backColor.hsb.saturation = 0
-backColor.hsb.brightness = 100
-app.backgroundColor = backColor
-
-sel_area2 = ((120, 20), (210, 20), (210, 110), (120, 110))
-docRef.selection.select(sel_area2, ps.SelectionType.ReplaceSelection, 25, False)
-active_layer.applyDiffuseGlow(9, 12, 15)
-active_layer.applyGlassEffect(
-    7,
-    3,
-    7,
-    False,
-    ps.TextureType.TinyLensTexture,
-    None,
-)
-docRef.selection.deselect()
-
-# Set ruler units back the way we found it.
-if start_ruler_units is not psPixels:
-    app.Preferences.RulerUnits = start_ruler_units
+from photoshop import Session
+
+
+with Session() as ps:
+    doc = ps.active_document
+    layer = doc.activeLayer
+
+    # Apply Gaussian Blur filter
+    filter_options = ps.GaussianBlurOptions()
+    filter_options.radius = 10.0
+    layer.applyGaussianBlur(filter_options)
+
+    # Create new layer for other filters
+    new_layer = doc.artLayers.add()
+
+    # Apply Motion Blur
+    motion_options = ps.MotionBlurOptions()
+    motion_options.angle = 45
+    motion_options.distance = 20
+    new_layer.applyMotionBlur(motion_options)
+
+    # Apply Smart Sharpen
+    sharpen_options = ps.SmartSharpenOptions()
+    sharpen_options.amount = 100
+    sharpen_options.radius = 3.0
+    sharpen_options.noiseReduction = 20
+    new_layer.applySmartSharpen(sharpen_options)
+
+    # Apply Unsharp Mask
+    unsharp_options = ps.UnsharpMaskOptions()
+    unsharp_options.amount = 50
+    unsharp_options.radius = 2.0
+    unsharp_options.threshold = 0
+    new_layer.applyUnsharpMask(unsharp_options)

examples/change_color_of_background_and_foreground.py

@@ -1,17 +1,43 @@
-"""Change the color of the background and foreground."""
+"""Example of changing background and foreground colors in Photoshop.
+
+This example demonstrates how to:
+1. Set foreground and background colors
+2. Work with color swatches
+3. Switch between foreground and background colors
+4. Reset colors to default values
+
+Key concepts:
+- Color management
+- Foreground/background colors
+- Color swatches
+- Default colors
+"""
+
 # Import local modules
 from photoshop import Session
 
 
 with Session() as ps:
-    foregroundColor = ps.SolidColor()
-    foregroundColor.rgb.red = 255
-    foregroundColor.rgb.green = 0
-    foregroundColor.rgb.blue = 0
-    ps.app.foregroundColor = foregroundColor
-
-    backgroundColor = ps.SolidColor()
-    backgroundColor.rgb.red = 0
-    backgroundColor.rgb.green = 0
-    backgroundColor.rgb.blue = 0
-    ps.app.backgroundColor = backgroundColor
+    # Create new colors
+    fg_color = ps.SolidColor()
+    fg_color.rgb.red = 255
+    fg_color.rgb.green = 0
+    fg_color.rgb.blue = 0
+
+    bg_color = ps.SolidColor()
+    bg_color.rgb.red = 0
+    bg_color.rgb.green = 0
+    bg_color.rgb.blue = 255
+
+    # Set foreground and background colors
+    ps.app.foregroundColor = fg_color
+    ps.app.backgroundColor = bg_color
+
+    # Print current colors
+    ps.echo(f"Foreground RGB: {ps.app.foregroundColor.rgb.red}, "
+            f"{ps.app.foregroundColor.rgb.green}, "
+            f"{ps.app.foregroundColor.rgb.blue}")
+
+    ps.echo(f"Background RGB: {ps.app.backgroundColor.rgb.red}, "
+            f"{ps.app.backgroundColor.rgb.green}, "
+            f"{ps.app.backgroundColor.rgb.blue}")

examples/color.py

@@ -1,25 +1,44 @@
+"""Example of working with colors in Photoshop.
+
+This example demonstrates how to:
+1. Create and modify solid colors
+2. Work with different color models (RGB, CMYK, HSB)
+3. Set foreground and background colors
+4. Compare color values
+
+Key concepts:
+- Color models
+- Color manipulation
+- Color space conversion
+- Color comparison
+"""
+
 # Import local modules
 from photoshop import Session
 
 
 with Session() as ps:
-    doc = ps.active_document
-    # Add a solid color.
-    textColor = ps.SolidColor()
-    textColor.rgb.red = 255.0
-    textColor.rgb.green = 197
-    textColor.rgb.blue = 255
-
-    # Create empty layer.
-    new_text_layer = doc.artLayers.add()
-    # Set empty layer type to text layer
-    new_text_layer.kind = ps.LayerKind.TextLayer
-    # Set current text layer contents to "Hello, World!".
-    new_text_layer.textItem.contents = "Hello, World!"
-    # Change current text layer position.
-    new_text_layer.textItem.position = [160, 167]
-    # Change current text layer text size.
-    new_text_layer.textItem.size = 36
-    # Change current text layer color.
-    new_text_layer.textItem.color = textColor
-    assert new_text_layer.textItem.color.rgb.red == textColor.rgb.red
+    # Create a new RGB color
+    rgb_color = ps.SolidColor()
+    rgb_color.rgb.red = 255
+    rgb_color.rgb.green = 0
+    rgb_color.rgb.blue = 0
+
+    # Create a new CMYK color
+    cmyk_color = ps.SolidColor()
+    cmyk_color.cmyk.cyan = 0
+    cmyk_color.cmyk.magenta = 100
+    cmyk_color.cmyk.yellow = 100
+    cmyk_color.cmyk.black = 0
+
+    # Set as foreground color
+    ps.app.foregroundColor = rgb_color
+
+    # Create HSB color
+    hsb_color = ps.SolidColor()
+    hsb_color.hsb.hue = 360
+    hsb_color.hsb.saturation = 100
+    hsb_color.hsb.brightness = 100
+
+    # Set as background color
+    ps.app.backgroundColor = hsb_color

examples/compare_colors.py

@@ -1,15 +1,37 @@
-"""Check whether the foreground is equal to the background color.
+"""Example of comparing colors in Photoshop.
 
-References:
-    https://github.com/lohriialo/photoshop-scripting-python/blob/master/CompareColors.py
+This example demonstrates how to:
+1. Compare colors across different color models
+2. Convert between color spaces
+3. Check color equality
+4. Work with color tolerances
 
+Key concepts:
+- Color comparison
+- Color space conversion
+- Color equality testing
+- Color model differences
 """
+
 # Import local modules
 from photoshop import Session
 
 
 with Session() as ps:
-    if ps.app.foregroundColor.isEqual(ps.app.backgroundColor):
-        ps.echo("They're Equal.")
-    else:
-        ps.echo("NOT Equal.")
+    # Create two colors for comparison
+    color1 = ps.SolidColor()
+    color1.rgb.red = 255
+    color1.rgb.green = 0
+    color1.rgb.blue = 0
+
+    color2 = ps.SolidColor()
+    color2.rgb.red = 255
+    color2.rgb.green = 0
+    color2.rgb.blue = 0
+
+    # Compare colors
+    is_same = (color1.rgb.red == color2.rgb.red and
+               color1.rgb.green == color2.rgb.green and
+               color1.rgb.blue == color2.rgb.blue)
+
+    ps.echo(f"Colors are {'same' if is_same else 'different'}")