Skip to contents

Get started with modFrames

Source: vignettes/modFrames.qmd

Introduction

modFrames is a Shiny UI module for the Artalytics platform that provides comprehensive frame analysis, timelapse visualization, and AI-powered creative journey storytelling for digital artwork creation processes.

Core Capabilities

  • Timelapse Playback: Animated frame-by-frame visualization with real-time metrics (strokes, time, colors)
  • Frame Comparison: Side-by-side comparison with visual difference highlighting using ImageMagick
  • Creative Journey Storytelling: Marketing-ready narrative insights generated from frame analytics
  • Interactive Visualization: Plotly-powered color evolution charts with phase boundaries

Module, Not App

modFrames is a module package, not a standalone application. It requires:

  • Parent app infrastructure from appPlatform
  • Reactive data context with artist/artwork UUIDs
  • Frame analytics data from artutils (frame_stats with 21 columns)
  • ImageMagick++ system library for difference image generation

For standalone testing during development, use inst/app/app.R.

System Requirements

CRITICAL: modFrames requires the ImageMagick++ C++ library:

  • Linux/Debian: sudo apt install libmagick++-dev
  • macOS: brew install imagemagick
  • Windows: Install ImageMagick with C++ headers from imagemagick.org

Without ImageMagick++, the {magick} package will not install and frame difference visualization will fail.

Ecosystem Position 

appPlatform (main Shiny app)
    |
modFrames, modGallery, modBrowse, ... (Shiny modules)
    |
artutils (data access layer)
    |
artcore (infrastructure: DB, CDN)

modFrames sits at the same level as other module packages, receiving artwork context from appPlatform and fetching frame data via artutils.

Quick Start

Installation 

# Requires GITHUB_PAT for private repo access
pak::pkg_install("artalytics/modFrames")

Basic Integration

Add modFrames to your Shiny app:

library(shiny)
library(bslib)
library(modFrames)

ui <- bslib::page_fluid(
  modFramesUI("frames")
)

server <- function(input, output, session) {
  r <- reactiveValues()

  observe({
    # Populate appdata from artutils
    r$appdata <- artutils::get_appdata(
      artist = "746b8207-72f5-4ab6-8d19-a91d03daec3d",
      artwork = "99da02ea-1ac0-4ea0-bfb9-e11a485b599b"
    )
  })

  modFramesServer("frames", r)
}

shinyApp(ui, server)

Reactive Data Structure

The r parameter passed to modFramesServer() must contain:

r <- reactiveValues(
  appdata = list(
    artwork = list(
      stats = list(
        artist_uuid = "746bxxxx-...",
        art_uuid = "99xxxxxx-..."
      ),
      frame_stats = data.table(...) # 21 columns from get_frame_analytics()
    ),
    config = list(
      n_frames = 150 # Total frames for this artwork
    )
  )
)

The frame_stats data.table contains 21 columns of per-frame analytics:

Category Columns
Identifiers art_uuid, artist_uuid, frame
Temporal elapsed_minutes, elapsed_hours, cumulative_strokes, estimated_bpm
Color unique_colors, total_pixels, dominant_hex, dominant_pixels, color_diversity, avg_red, avg_green, avg_blue
Delta colors_added, colors_removed, pixels_added, palette_change_score
Phase technique_phase
Metadata created_utc

This structure is automatically populated by artutils::get_appdata().

Environment Variables

modFrames inherits environment variables from its dependencies:

Database (via artcore):

  • ART_PGHOST - PostgreSQL host
  • ART_PGPORT - PostgreSQL port (default: 5432)
  • ART_PGUSER - Database user
  • ART_PGPASS - Database password

CDN (via artcore):

  • ART_BUCKETS_KEY_ID - DigitalOcean Spaces key ID
  • ART_BUCKETS_KEY_SECRET - Spaces secret key

Next Steps

For questions and issues, visit the GitHub repository.