AdventureTemplate¶

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_crown(self) -> None:
    """Enable layers which make-up the Legendary crown."""

    # Enable crown and legendary border
    self.crown_layer.visible = True
    if self.border_group and isinstance(self.border_group, LayerContainer):
        psd.getLayer(LAYERS.NORMAL_BORDER, self.border_group).visible = False
        psd.getLayer(LAYERS.LEGENDARY_BORDER, self.border_group).visible = True

    # Call hollow crown step
    if self.is_hollow_crown:
        self.enable_hollow_crown(
            psd.getLayer(LAYERS.SHADOWS))

def enable_frame_layers(self) -> None:
    """Enable layers which make-up the frame of the card."""

    # Twins
    if self.twins_layer:
        self.twins_layer.visible = True

    # PT Box
    if self.is_creature and self.pt_layer:
        self.pt_layer.visible = True

    # Pinlines
    if self.pinlines_layer:
        self.pinlines_layer.visible = True

    # Color Indicator
    if self.is_type_shifted and self.color_indicator_layer:
        self.color_indicator_layer.visible = True

    # Background
    if self.background_layer:
        self.background_layer.visible = True

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

def enable_hollow_crown(self, shadows: Optional[ArtLayer] = None) -> None:
    """Enable the hollow legendary crown."""
    if shadows:
        psd.enable_mask(shadows)
    psd.enable_mask(self.crown_layer.parent)
    psd.enable_mask(self.pinlines_layer.parent)
    self.crown_shadow_layer.visible = True

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}'")

@classmethod
def get_template_route(cls, layout, **kwargs) -> 'BaseTemplate':
    """Overwrite this method to reroute a template class to another class under a set of
    conditions. See the 'IxalanTemplate' class for an example.

    Args:
        layout: The card layout object.

    Returns:
        Initialized template class object.
    """
    return super().__new__(cls)

def hook_creature(self) -> None:
    """Run this if card is a creature."""
    pass

def hook_large_mana(self) -> None:
    """Run this if card has a large mana symbol."""
    pass

def load_artwork(
    self,
    art_file: Optional[str | Path] = None,
    art_layer: Optional[ArtLayer] = None,
    art_reference: Optional[ReferenceLayer] = None
) -> None:
    """Loads the specified art file into the specified layer.

    Args:
        art_file: Optional path (as str or Path) to art file. Will use `self.layout.art_file`
            if not provided.
        art_layer: Optional `ArtLayer` where art image should be placed when imported. Will use `self.art_layer`
            property if not provided.
        art_reference: Optional `ReferenceLayer` that should be used to position and scale the imported
            image. Will use `self.art_reference` property if not provided.`
    """

    # Set default values
    art_file = art_file or self.layout.art_file
    art_layer = art_layer or self.art_layer
    art_reference = art_reference or self.art_reference

    # Check for full-art test image
    if ENV.TEST_MODE and self.is_fullart:
        art_file = PATH.SRC_IMG / "test-fa.jpg"

    # Import art file
    if self.art_action:
        # Use action pipeline
        art_layer = psd.paste_file(
            layer=art_layer,
            path=art_file,
            action=self.art_action,
            action_args=self.art_action_args,
            docref=self.docref)
    else:
        # Use traditional pipeline
        art_layer = psd.import_art(
            layer=art_layer,
            path=art_file,
            docref=self.docref)
    self.active_layer = art_layer

    # Frame the artwork
    psd.frame_layer(
        layer=art_layer,
        ref=art_reference)

    # Perform content aware fill if needed
    if self.is_content_aware_enabled:

        # Perform a generative fill
        if CFG.generative_fill:
            if _doc_generated := psd.generative_fill_edges(
                layer=art_layer,
                feather=CFG.feathered_fill,
                close_doc=bool(not CFG.select_variation),
                docref=self.docref
            ):
                # Document reference was returned, await user intervention
                self.console.await_choice(
                    self.event, msg="Select a Generative Fill variation, then click Continue ...")
                _doc_generated.close(SaveOptions.SaveChanges)
            return

        # Perform a content aware fill
        psd.content_aware_fill_edges(
            layer=art_layer,
            feather=CFG.feathered_fill)

def load_expansion_symbol(self) -> None:
    """Imports and positions the expansion symbol SVG image."""

    # Check for expansion symbol disabled
    if not CFG.symbol_enabled or not self.expansion_reference:
        return
    if not self.layout.symbol_svg:
        return self.log("Expansion symbol disabled, SVG file not found.")

    # Try to import the expansion symbol
    try:

        # Import and place the symbol
        svg = psd.import_svg(
            path=str(self.layout.symbol_svg),
            ref=self.expansion_reference,
            placement=ElementPlacement.PlaceBefore,
            docref=self.docref)

        # Frame the symbol
        psd.frame_layer_by_height(
            layer=svg,
            ref=self.expansion_reference,
            alignments=self.expansion_symbol_alignments)

        # Rename and reset property
        svg.name = 'Expansion Symbol'
        self.expansion_symbol_layer = svg

    except Exception as e:
        return self.log('Expansion symbol disabled due to an error.', e)

def log(self, text: str, e: Optional[Exception] = None) -> None:
    """Writes a message to console if test mode isn't enabled, logs an exception if provided.

    Args:
        text: Message to write to console.
        e: Exception to log if provided.
    """
    if e:
        self.console.log_exception(e)
    if not ENV.TEST_MODE:
        self.console.update(text)

def paste_scryfall_scan(self, rotate: bool = False, visible: bool = True) -> Optional[ArtLayer]:
    """Downloads the card's scryfall scan, pastes it into the document next to the active layer,
    and frames it to fill the given reference layer.

    Args:
        rotate: Will rotate the card horizontally if True, useful for Planar cards.
        visible: Whether to leave the layer visible or hide it.

    Returns:
        ArtLayer if Scryfall scan was imported, otherwise None.
    """
    # Try to grab the scan from Scryfall
    if not self.layout.scryfall_scan:
        return
    scryfall_scan = get_card_scan(self.layout.scryfall_scan)
    if not scryfall_scan:
        return

    # Paste the scan into a new layer
    if layer := psd.import_art_into_new_layer(
            path=scryfall_scan,
            name="Scryfall Reference",
            docref=self.docref
    ):
        # Rotate the layer if necessary
        if rotate:
            layer.rotate(90)

        # Frame the layer and position it above the art layer
        bleed = int(self.docref.resolution / 8)
        dims = psd.get_dimensions_from_bounds(
            (bleed, bleed, self.docref.width - bleed, self.docref.height - bleed))
        psd.frame_layer(layer, dims)
        layer.move(self.art_layer, ElementPlacement.PlaceBefore)
        layer.visible = visible
        return layer