AdventureVectorTemplate¶

def add_basic_watermark_snow_effects(self, wm: ArtLayer):
    """Adds optional snow effects for 'Snow' Basic Land watermarks.

    Args:
        wm: ArtLayer containing the Basic Land Watermark.
    """
    pass

def basic_text_layers(self) -> None:
    """Add essential text layers: Mana cost, Card name, Typeline."""
    self.text.extend([
        FormattedTextField(
            layer=self.text_layer_mana,
            contents=self.layout.mana_cost
        ),
        ScaledTextField(
            layer=self.text_layer_name,
            contents=self.layout.name,
            reference=self.name_reference
        ),
        ScaledTextField(
            layer=self.text_layer_type,
            contents=self.layout.type_line,
            reference=self.type_reference
        )])

def check_photoshop(self) -> None:
    """Check if Photoshop is responsive to automation."""
    # Ensure the Photoshop Application is responsive
    check = self.app.refresh_app()
    if not isinstance(check, OSError):
        return

    # Connection with Photoshop couldn't be established, try again?
    if not self.console.await_choice(
            self.event, get_photoshop_error_message(check),
            end="Hit Continue to try again, or Cancel to end the operation.\n\n"
    ):
        # Cancel the operation
        raise OSError(check)
    self.check_photoshop()

def collector_info(self) -> None:
    """Format and add the collector info at the bottom."""

    # Ignore this step if legal layer not present
    if not self.legal_group:
        return

    # If creator is specified add the text
    if self.layout.creator and self.text_layer_creator:
        self.text_layer_creator.textItem.contents = self.layout.creator

    # Which collector info mode?
    if CFG.collector_mode in [
        CollectorMode.Default, CollectorMode.Modern
    ] and self.layout.collector_data:
        return self.collector_info_authentic()
    elif CFG.collector_mode == CollectorMode.ArtistOnly:
        return self.collector_info_artist_only()
    return self.collector_info_basic()

def collector_info_artist_only(self) -> None:
    """Called to generate 'Artist Only' collector info."""

    # Collector layers
    artist_layer = psd.getLayer(LAYERS.ARTIST, self.legal_group)
    psd.getLayer(LAYERS.SET, self.legal_group).visible = False

    # Correct color for non-black border
    if self.border_color != BorderColor.Black:
        artist_layer.textItem.color = self.RGB_BLACK

    # Insert artist name
    psd.replace_text(artist_layer, "Artist", self.layout.artist)

def collector_info_authentic(self) -> None:
    """Called to generate realistic collector info."""

    # Hide basic layers
    psd.getLayer(LAYERS.ARTIST, self.legal_group).visible = False
    psd.getLayer(LAYERS.SET, self.legal_group).visible = False

    # Get the collector layers
    group = psd.getLayerSet(LAYERS.COLLECTOR, self.legal_group)
    top = psd.getLayer(LAYERS.TOP, group).textItem
    bottom = psd.getLayer(LAYERS.BOTTOM, group)
    group.visible = True

    # Correct color for non-black border
    if self.border_color != 'black':
        top.color = self.RGB_BLACK
        bottom.textItem.color = self.RGB_BLACK

    # Fill in language if needed
    if self.layout.lang != "en":
        psd.replace_text(bottom, "EN", self.layout.lang.upper())

    # Fill optional collector star
    if self.is_collector_promo:
        psd.replace_text(bottom, "•", MagicIcons.COLLECTOR_STAR)

    # Apply the collector info
    top.contents = self.layout.collector_data
    psd.replace_text(bottom, "SET", self.layout.set)
    psd.replace_text(bottom, "Artist", self.layout.artist)

def collector_info_basic(self) -> None:
    """Called to generate basic collector info."""

    # Collector layers
    artist_layer = psd.getLayer(LAYERS.ARTIST, self.legal_group)
    set_layer = psd.getLayer(LAYERS.SET, self.legal_group)
    set_TI = set_layer.textItem

    # Correct color for non-black border
    if self.border_color != BorderColor.Black:
        set_TI.color = self.RGB_BLACK
        artist_layer.textItem.color = self.RGB_BLACK

    # Fill optional collector star
    if self.is_collector_promo:
        psd.replace_text(set_layer, "•", MagicIcons.COLLECTOR_STAR)

    # Fill language, artist, and set
    if self.layout.lang != "en":
        psd.replace_text(set_layer, "EN", self.layout.lang.upper())
    psd.replace_text(artist_layer, "Artist", self.layout.artist)
    set_TI.contents = self.layout.set + set_TI.contents

@try_photoshop
def color_border(self) -> None:
    """Color this card's border based on given setting."""
    if self.border_color != BorderColor.Black:
        psd.apply_fx(self.border_group, [EffectColorOverlay(color=psd.get_color(self.border_color))])

def create_basic_watermark(self) -> None:
    """Builds a basic land watermark."""

    # Generate the watermark
    wm = psd.import_svg(
        path=self.layout.watermark_basic,
        ref=self.text_group,
        placement=ElementPlacement.PlaceAfter,
        docref=self.docref)
    psd.frame_layer_by_height(
        layer=wm,
        ref=self.textbox_reference.dims,
        scale=75)

    # Add effects
    psd.apply_fx(wm, self.basic_watermark_fx)

    # Add snow effects
    if self.is_snow:
        self.add_basic_watermark_snow_effects(wm)

    # Remove rules text step
    self.rules_text_and_pt_layers = lambda: None
    self.layout.oracle_text = ''
    self.layout.flavor_text = ''

def create_blended_layer(
        self,
        group: LayerSet,
        colors: Union[None, str, list[str]] = None,
        masks: Optional[list[ArtLayer]] = None,
        **kwargs
):
    """Either enable a single frame layer or create a multicolor layer using a gradient mask.

    Args:
        group: Group to look for the color layers within.
        colors: Color layers to look for.
        masks: Masks to use for blending the layers.
    """
    # Ensure masks is a list
    masks = masks or []

    # Establish our colors
    colors = colors or self.identity or self.pinlines
    if isinstance(colors, str) and not is_multicolor_string(colors):
        # Received a color string that isn't a frame color combination
        colors = [colors]
    elif len(colors) >= self.color_limit:
        # Received too big a color combination, revert to pinlines
        colors = [self.pinlines]
    elif isinstance(colors, str):
        # Convert string of colors to list
        colors = list(colors)

    # Single layer
    if len(colors) == 1:
        layer = psd.getLayer(colors[0], group)
        layer.visible = True
        return

    # Enable each layer color
    layers: list[ArtLayer] = []
    for i, color in enumerate(colors):

        # Make layer visible
        layer = psd.getLayer(color, group)
        if 'blend_mode' in kwargs:
            layer.blendMode = kwargs['blend_mode']
        layer.visible = True

        # Position the new layer and add a mask to previous, if previous layer exists
        if layers and len(masks) >= i:
            layer.move(layers[i - 1], ElementPlacement.PlaceAfter)
            psd.copy_layer_mask(masks[i - 1], layers[i - 1])

        # Add to the layer list
        layers.append(layer)

@staticmethod
def create_blended_solid_color(
        group: LayerSet,
        colors: list[ColorObject],
        masks: Optional[list[Union[ArtLayer, LayerSet]]] = None,
        **kwargs
) -> None:
    """Either enable a single frame layer or create a multicolor layer using a gradient mask.

    Args:
        group: Group to look for the color layers within.
        colors: Color layers to look for.
        masks: Masks to use for blending the layers.

    Keyword Args:
        blend_mode (BlendMode): Sets the blend mode of the generated solid color layers.
    """
    # Ensure masks is a list
    masks = masks or []

    # Enable each layer color
    layers: list[ArtLayer] = []
    for i, color in enumerate(colors):
        layer = psd.smart_layer(psd.create_color_layer(color, group))
        if 'blend_mode' in kwargs:
            layer.blendMode = kwargs['blend_mode']

        # Position the new layer and add a mask to previous, if previous layer exists
        if layers and len(masks) >= i:
            layer.move(layers[i - 1], ElementPlacement.PlaceAfter)
            psd.copy_layer_mask(masks[i - 1], layers[i - 1])
        layers.append(layer)

def create_watermark(self) -> None:
    """Builds the watermark."""
    # Required values to generate a Watermark
    if not all([
        self.layout.watermark_svg,
        self.layout.watermark,
        self.textbox_reference,
        self.watermark_colors,
        self.text_group
    ]):
        return

    # Get watermark custom settings if available
    wm_details = CON.watermarks.get(self.layout.watermark, {})

    # Import and frame the watermark
    wm = psd.import_svg(
        path=self.layout.watermark_svg,
        ref=self.text_group,
        placement=ElementPlacement.PlaceAfter,
        docref=self.docref)
    psd.frame_layer(
        layer=wm,
        ref=self.textbox_reference.dims,
        smallest=True,
        scale=wm_details.get('scale', 80))

    # Apply opacity, blending, and effects
    wm.opacity = wm_details.get('opacity', CFG.watermark_opacity)
    wm.blendMode = self.watermark_blend_mode
    psd.apply_fx(wm, self.watermark_fx)

def enable_adventure_layers(self) -> None:
    """Add and modify layers required for Adventure cards."""

    # Pinlines
    self.generate_layer(
        group=self.adventure_pinlines_group,
        colors=self.pinlines_colors)

    # Wings
    self.generate_layer(
        group=self.adventure_wings_group,
        colors=self.adventure_wings_colors)

    # textbox
    self.generate_layer(
        group=self.adventure_textbox_group,
        colors=self.adventure_textbox_colors,
        masks=self.adventure_textbox_masks)

    # Adventure Name
    self.generate_layer(
        group=self.adventure_name_group,
        colors=self.adventure_name_colors)

    # Adventure Typeline
    self.generate_layer(
        group=self.adventure_typeline_group,
        colors=self.adventure_typeline_colors)

    # Adventure Accent
    self.generate_layer(
        group=self.adventure_typeline_accent_group,
        colors=self.adventure_typeline_accent_colors)

def enable_frame_layers(self) -> None:
    """Build the card frame by enabling and/or generating various layer."""

    # Enable vector shapes
    self.enable_shape_layers()

    # Enable layer masks
    self.enable_layer_masks()

    # PT Box -> Single static layer
    if self.is_creature and self.pt_group:
        self.pt_group.visible = True
        self.generate_layer(
            group=self.pt_group,
            colors=self.pt_colors,
            masks=self.pt_masks)

    # Color Indicator -> Blended solid color layers
    if self.is_type_shifted and self.indicator_group:
        self.generate_layer(
            group=self.indicator_group,
            colors=self.indicator_colors,
            masks=self.indicator_masks)

    # Pinlines -> Solid color or gradient layers
    for group in [g for g in self.pinlines_groups if g]:
        group.visible = True
        self.generate_layer(
            group=group,
            colors=self.pinlines_colors,
            masks=self.pinlines_masks)

    # Twins -> Blended texture layers
    if self.twins_group:
        self.generate_layer(
            group=self.twins_group,
            colors=self.twins_colors,
            masks=self.twins_masks)

    # Textbox -> Blended texture layers
    if self.textbox_group:
        self.generate_layer(
            group=self.textbox_group,
            colors=self.textbox_colors,
            masks=self.textbox_masks)

    # Background layer -> Blended texture layers
    if self.background_group:
        self.generate_layer(
            group=self.background_group,
            colors=self.background_colors,
            masks=self.background_masks)

    # Legendary crown
    if self.is_legendary:
        self.enable_crown()

def enable_hollow_crown(self, **kwargs) -> None:
    """Enable the Hollow Crown within the Legendary Crown, only called if card is Legendary Nyx or Companion.

    Keyword Args:
        masks (list[ArtLayer | LayerSet]): List of layers containing masks to enable.
        vector_masks (list[ArtLayer | LayerSet]): List of layers containing vector masks to enable.
    """

    # Layer masks to enable
    for m in kwargs.get('masks', []):
        psd.enable_mask(m)

    # Vector masks to enable
    for m in kwargs.get('vector_masks', []):
        psd.enable_vector_mask(m)

    # Enable shadow
    if self.crown_shadow_layer:
        self.crown_shadow_layer.visible = True

def enable_layer_masks(self) -> None:
    """Enable or copy required layer masks provided by `enabled_masks`."""

    # For each mask enabled, apply it based on given notation
    for mask in [m for m in self.enabled_masks if m]:

        # Dict notation, complex mask behavior
        if isinstance(mask, dict):

            # Copy to a layer?
            if layer := mask.get('layer'):
                # Copy normal or vector mask to layer
                func = psd.copy_vector_mask if mask.get('vector') else psd.copy_layer_mask
                func(mask.get('mask'), layer)
            else:
                # Enable normal or vector mask
                layer = mask.get('mask')
                func = psd.enable_vector_mask if mask.get('vector') else psd.enable_mask
                func(layer)

            # Apply extra functions
            [f(layer) for f in mask.get('funcs', [])]

        # List notation, copy from one layer to another
        elif isinstance(mask, list):
            psd.copy_layer_mask(*mask)

        # Single layer to enable mask on
        elif isinstance(mask, LayerObject):
            psd.enable_mask(mask)

def enable_shape_layers(self) -> None:
    """Enable required vector shape layers provided by `enabled_shapes`."""
    def _enable_shape(_shapes: Union[LayerObjectTypes, list[LayerObjectTypes], None]) -> None:
        for x in _shapes:
            if not x:
                continue
            if isinstance(x, list):
                _enable_shape(x)
            else:
                x.visible = True
    _enable_shape(self.enabled_shapes)

def execute(self) -> bool:
    """Perform actions to render the card using this template.

    Notes:
        - Each action is wrapped in an exception check and breakpoint to cancel the thread
            if a cancellation signal was sent by the user.
        - Never override this method!
    """
    # Preliminary Photoshop check
    if not self.run_tasks(
        funcs=[self.check_photoshop],
        message="Unable to reach Photoshop!"
    ):
        return False

    # Pre-process layout data
    if not self.run_tasks(
        funcs=self.pre_render_methods,
        message="Pre-processing layout data failed!"
    ):
        return False

    # Load in the PSD template
    if not self.run_tasks(
        funcs=[self.app.load],
        message="PSD template failed to load!",
        args=[str(self.layout.template_file)]
    ):
        return False

    # Load in artwork and frame it
    if not self.run_tasks(
        funcs=[self.load_artwork],
        message="Unable to load artwork!"
    ):
        return False

    # Load in Scryfall scan and frame it
    if CFG.import_scryfall_scan:
        self.run_tasks(
            funcs=[self.paste_scryfall_scan],
            message="Couldn't import Scryfall scan, continuing without it!",
            warning=True)

    # Add expansion symbol
    self.run_tasks(
        funcs=[self.load_expansion_symbol],
        message="Unable to generate expansion symbol!",
        warning=True)

    # Add watermark
    if CFG.enable_basic_watermark and self.is_basic_land:
        # Basic land watermark
        if not self.run_tasks(
            funcs=[self.create_basic_watermark],
            message="Unable to generate basic land watermark!"
        ):
            return False
    elif CFG.watermark_mode is not WatermarkMode.Disabled:
        # Normal watermark
        if not self.run_tasks(
            funcs=[self.create_watermark],
            message="Unable to generate watermark!"
        ):
            return False

    # Enable layers to build our frame
    if not self.run_tasks(
        funcs=self.frame_layer_methods,
        message="Enabling layers failed!"
    ):
        return False

    # Format text layers
    if not self.run_tasks(
        funcs=[
            *self.text_layer_methods,
            self.format_text_layers,
            *self.post_text_methods
        ],
        message="Formatting text layers failed!"
    ):
        return False

    # Specific hooks
    if not self.run_tasks(
        funcs=self.hooks,
        message="Encountered an error during triggered hooks step!"
    ):
        return False

    # Manual edit step?
    if CFG.exit_early and not ENV.TEST_MODE:
        self.console.await_choice(self.event)

    # Save the document
    if not self.run_tasks(
        funcs=[self.save_mode],
        message="Error during file save process!",
        kwargs={'path': self.output_file_name, 'docref': self.docref}
    ):
        return False

    # Post save methods
    if not self.run_tasks(
        funcs=self.post_save_methods,
        message="Image saved, but an error was encountered during the post-save step!"
    ):
        return False

    # Reset document, return success
    if not ENV.TEST_MODE:
        self.console.update(f"[b]{self.output_file_name.stem}[/b] rendered successfully!")
    self.reset()
    return True

def format_text_layers(self) -> None:
    """Validate and execute each formatted text layer."""
    for t in self.text:
        # Check for cancelled thread each iteration
        if self.event.is_set():
            return
        # Validate and execute
        if t and t.validate():
            t.execute()

def generate_layer(
        self, group: Union[ArtLayer, LayerSet],
        colors: Union[str, ColorObject, list[ColorObject], list[dict]],
        masks: Optional[list[ArtLayer]] = None,
        **kwargs
) -> Optional[ArtLayer]:
    """Takes information about a frame layer group and routes it to the correct
    generation function which blends rasterized layers, blends solid color layers, or
    generates a solid color/gradient adjustment layer.

    Notes:
        The result for a given 'colors' schema:
        - str: Enable and/or blend one or more texture layers, unless string is a hex color, in which
            case create a solid color adjustment layer.
        - list[str]: Blend multiple texture layers.
        - list[int]: Create a solid color adjustment layer.
        - list[dict]: Create a gradient adjustment layer.
        - list[list[int]]: Blend multiple solid color adjustment layers.
        - list[SolidColor]: Blend multiple solid color adjustment layers.

    Args:
        group: Layer or group containing layers.
        colors: Color definition for this frame layer generation.
        masks: Masks used to blend this generated layer.
    """
    # Assign a generator task based on colors value
    if isinstance(colors, str):
        # Example: '#FFFFFF'
        # Single adjustment layer
        if colors.startswith('#'):
            return psd.create_color_layer(
                color=colors,
                layer=group,
                docref=self.docref,
                **kwargs)
        # Example: 'Land'
        # Single or blended texture layers
        return self.create_blended_layer(
            group=group,
            colors=colors,
            masks=masks,
            **kwargs)
    elif isinstance(colors, SolidColor):
        # Example: SolidColor
        # Single adjustment layer
        return psd.create_color_layer(
            color=colors,
            layer=group,
            docref=self.docref,
            **kwargs
        )
    elif isinstance(colors, list):
        if all(isinstance(c, str) for c in colors):
            # Example: ['#000000', '#FFFFFF', ...]
            # Blended RGB/CMYK adjustment layers
            if colors[0].startswith('#'):  # noqa
                return self.create_blended_solid_color(
                    group=group,
                    colors=colors,
                    masks=masks,
                    **kwargs)
            # Example: ['W', 'U']
            # Blended texture layers
            return self.create_blended_layer(
                group=group,
                colors=colors,
                masks=masks,
                **kwargs)
        elif all(isinstance(c, int) for c in colors):
            # Example: [r, g, b]
            # RGB/CMYK adjustment layer
            return psd.create_color_layer(
                color=colors,
                layer=group,
                docref=self.docref,
                **kwargs)
        elif all(isinstance(c, dict) for c in colors):
            # Example: [GradientColor, GradientColor, ...]
            # Gradient adjustment layer
            return psd.create_gradient_layer(
                colors=colors,
                layer=group,
                docref=self.docref,
                **kwargs)
        elif all(isinstance(c, (list, SolidColor)) for c in colors):
            # Example 1: [[r, g, b], [r, g, b], ...]
            # Example 2: [SolidColor, SolidColor, ...]
            # Blended RGB/CMYK adjustment layers
            return self.create_blended_solid_color(
                group=group,
                colors=colors,
                masks=masks,
                **kwargs)

    # Failed to match a recognized color notation
    if group:
        self.log(f"Couldn't generate frame element: '{group.name}'")