Palette Generator Master #

A powerful Flutter package for extracting prominent colors from images with advanced features including multi-color space support, accessibility compliance, and color harmony generation.

This package is a complete rewrite and enhancement of the discontinued palette_generator package (0.3.3+7) with modern Flutter development practices, enhanced performance, and new capabilities.

✨ Features #

🎨 Advanced Color Extraction #

Multi-color space support: RGB, HSV, and LAB color spaces for more accurate analysis
Enhanced quantization algorithms for better color clustering
Improved dominant color detection with advanced scoring
Customizable target colors (vibrant, muted, light, dark variations)

♿ Accessibility First #

WCAG 2.1 compliance checking for color contrast
Automatic contrast ratio calculation between color pairs
Best text color selection for any background color
Accessible color pair generation with customizable contrast thresholds

🌈 Color Harmony #

Automatic harmony generation based on color theory principles
Complementary, analogous, triadic, and split-complementary color schemes
Customizable harmony algorithms for different design needs

⚡ Performance & Quality #

Optimized algorithms for faster processing
Memory-efficient color analysis with 5-bit quantization
Null safety throughout the codebase
Modern Flutter practices with comprehensive error handling
Timeout management for network images

🚀 Getting Started #

Installation #

Add this package to your pubspec.yaml:

dependencies:
  palette_generator_master: ^1.1.0

Then run:

flutter pub get

Basic Usage #

import 'package:flutter/material.dart';
import 'package:palette_generator_master/palette_generator_master.dart';

// Generate palette from an image
Future<void> generatePalette() async {
  // Load your image
  final ImageProvider imageProvider = AssetImage('assets/my_image.jpg');
  
  // Generate palette
  final PaletteGeneratorMaster paletteGenerator = 
      await PaletteGeneratorMaster.fromImageProvider(
    imageProvider,
    maximumColorCount: 16,
    generateHarmony: true,      // Generate color harmony
  );
  
  // Access extracted colors
  final Color? dominantColor = paletteGenerator.dominantColor?.color;
  final Color? vibrantColor = paletteGenerator.vibrantColor?.color;
  final Color? mutedColor = paletteGenerator.mutedColor?.color;
  
  // Get all extracted colors
  final List<PaletteColorMaster> allColors = paletteGenerator.paletteColors;
  
  // Get harmony colors
  final List<ColorHarmonyMaster> harmonyColors = paletteGenerator.harmonyColors;
  
  // Use colors in your UI
  return Container(
    color: dominantColor,
    child: Text(
      'Dominant Color',
      style: TextStyle(
        color: paletteGenerator.getBestTextColorFor(dominantColor!),
      ),
    ),
  );
}

📖 Advanced Usage #

Custom Color Targets #

final PaletteGeneratorMaster generator = 
    await PaletteGeneratorMaster.fromImageProvider(
  imageProvider,
  targets: [
    PaletteTargetMaster.vibrant,
    PaletteTargetMaster.darkVibrant,
    PaletteTargetMaster.lightMuted,
    // Create custom target
    PaletteTargetMaster(
      saturationWeight: 0.8,
      lightnessWeight: 0.6,
      populationWeight: 0.4,
      minimumSaturation: 0.3,
      maximumSaturation: 0.9,
      minimumLightness: 0.2,
      maximumLightness: 0.8,
      targetSaturation: 0.6,
      targetLightness: 0.5,
      isExclusive: true,
    ),
  ],
);

Accessibility Features #

// Get accessible color pairs
final List<AccessibleColorPair> accessiblePairs = 
    generator.getAccessibleColorPairs(
  minimumContrast: 4.5, // WCAG AA standard
);

// Check each pair
for (var pair in accessiblePairs) {
  print('Foreground: ${pair.foreground}');
  print('Background: ${pair.background}');
  print('Contrast Ratio: ${pair.contrastRatio}');
  print('Meets WCAG AA: ${pair.meetsWcagAA}');
  print('Meets WCAG AAA: ${pair.meetsWcagAAA}');
}

// Get best text color for a background
final Color backgroundColor = Colors.blue;
final Color textColor = generator.getBestTextColorFor(
  backgroundColor,
  minimumContrast: 4.5,
);

// Check contrast ratio between two colors
final double contrastRatio = AccessibilityHelperMaster.calculateContrastRatio(
  Colors.white,
  Colors.blue,
);

Working with Different Image Sources #

// From asset image
final generator1 = await PaletteGeneratorMaster.fromImageProvider(
  AssetImage('assets/image.jpg'),
);

// From network image with custom timeout
final generator2 = await PaletteGeneratorMaster.fromImageProvider(
  NetworkImage('https://example.com/image.jpg'),
  timeout: Duration(seconds: 30),
  maximumColorCount: 24,
);

// From ui.Image
final ui.Image image = await loadImageFromSomewhere();
final generator3 = await PaletteGeneratorMaster.fromImage(
  image,
  region: Rect.fromLTWH(0, 0, 100, 100), // Process only a region
);

// From byte data
final ByteData imageData = await loadImageBytes();
final generator4 = await PaletteGeneratorMaster.fromByteData(
  EncodedImageMaster(
    imageData,
    width: 800,
    height: 600,
    name: 'my_image',
  ),
  maximumColorCount: 16,
);

// From network with error handling
try {
  final generator = await PaletteGeneratorMaster.fromImageProvider(
    NetworkImage('https://example.com/image.jpg'),
    timeout: Duration(seconds: 10),
  );
} catch (e) {
  print('Failed to load image: $e');
  // Handle error gracefully
}

Color Analysis and Information #

// Get detailed color information
final PaletteColorMaster dominant = generator.dominantColor!;
print('Color: ${dominant.color}');
print('Population: ${dominant.population}');
print('Luminance: ${dominant.luminance}');
print('Is Dark: ${dominant.isDark}');
print('Is Light: ${dominant.isLight}');

// Get all colors with their populations
for (var color in generator.paletteColors) {
  print('Color: ${color.color}, Population: ${color.population}');
}

// Get specific target colors
final vibrant = generator.vibrantColor;
final lightVibrant = generator.lightVibrantColor;
final darkVibrant = generator.darkVibrantColor;
final muted = generator.mutedColor;
final lightMuted = generator.lightMutedColor;
final darkMuted = generator.darkMutedColor;

Color Harmony Examples #

// Generate harmony colors
final generator = await PaletteGeneratorMaster.fromImageProvider(
  imageProvider,
  generateHarmony: true,
);

// Use different harmony types
for (var harmony in generator.harmonyColors) {
  switch (harmony.type) {
    case HarmonyType.complementary:
      print('Complementary colors: ${harmony.colors}');
      break;
    case HarmonyType.analogous:
      print('Analogous colors: ${harmony.colors}');
      break;
    case HarmonyType.triadic:
      print('Triadic colors: ${harmony.colors}');
      break;
    case HarmonyType.splitComplementary:
      print('Split complementary colors: ${harmony.colors}');
      break;
  }
}

// Create a color scheme widget
Widget buildColorScheme(PaletteGeneratorMaster generator) {
  final dominant = generator.dominantColor!.color;
  final harmonies = generator.harmonyColors;
  
  return Column(
    children: [
      Container(color: dominant, height: 50),
      if (harmonies.isNotEmpty)
        for (var harmony in harmonies.first.colors)
          Container(color: harmony, height: 50),
    ],
  );
}

Custom Filters #

// Create custom filter to exclude specific colors
bool excludeRedColors(HSLColor color) {
  // Exclude colors with high red saturation
  return color.hue < 350 && color.hue > 10;
}

// Create filter for pastel colors only
bool pastelColorsOnly(HSLColor color) {
  return color.saturation < 0.3 && color.lightness > 0.7;
}

// Use custom filters
final generator = await PaletteGeneratorMaster.fromImageProvider(
  imageProvider,
  filters: [
    avoidRedBlackWhitePaletteFilterMaster,
    excludeRedColors,
    pastelColorsOnly,
  ],
);

🎯 API Reference #

PaletteGeneratorMaster #

The main class for generating color palettes from images.

Static Methods

// Generate from ImageProvider
static Future<PaletteGeneratorMaster> fromImageProvider(
  ImageProvider imageProvider, {
  Size? size,
  Rect? region,
  int maximumColorCount = 16,
  List<PaletteFilterMaster> filters = const [avoidRedBlackWhitePaletteFilterMaster],
  List<PaletteTargetMaster> targets = const [],
  Duration timeout = const Duration(seconds: 15),
  ColorSpace colorSpace = ColorSpace.rgb,
  bool generateHarmony = true,
})

// Generate from ui.Image
static Future<PaletteGeneratorMaster> fromImage(
  ui.Image image, {
  Rect? region,
  int maximumColorCount = 16,
  List<PaletteFilterMaster> filters = const [avoidRedBlackWhitePaletteFilterMaster],
  List<PaletteTargetMaster> targets = const [],
  ColorSpace colorSpace = ColorSpace.rgb,
  bool generateHarmony = true,
})

// Generate from encoded image data
static Future<PaletteGeneratorMaster> fromByteData(
  EncodedImageMaster encodedImage, {
  Rect? region,
  int maximumColorCount = 16,
  List<PaletteFilterMaster> filters = const [avoidRedBlackWhitePaletteFilterMaster],
  List<PaletteTargetMaster> targets = const [],
  ColorSpace colorSpace = ColorSpace.rgb,
  bool generateHarmony = true,
})

Properties

// Target colors
PaletteColorMaster? get vibrantColor;
PaletteColorMaster? get lightVibrantColor;
PaletteColorMaster? get darkVibrantColor;
PaletteColorMaster? get mutedColor;
PaletteColorMaster? get lightMutedColor;
PaletteColorMaster? get darkMutedColor;
PaletteColorMaster? get dominantColor;

// All extracted colors
List<PaletteColorMaster> get paletteColors;
Iterable<Color> get colors;

// Harmony colors (if generated)
List<ColorHarmonyMaster> get harmonyColors;

// Source image info
ImageInfoMaster? get sourceImageInfo;

Methods

// Get accessible color pairs
List<AccessibleColorPair> getAccessibleColorPairs({
  double minimumContrast = 4.5,
});

// Get best text color for background
Color getBestTextColorFor(
  Color backgroundColor, {
  double minimumContrast = 4.5,
});

PaletteColorMaster #

Represents a color in the palette with additional information.

class PaletteColorMaster {
  final Color color;
  final int population;
  
  // Properties
  double get luminance;
  bool get isDark;
  bool get isLight;
}

PaletteTargetMaster #

Defines target characteristics for color extraction.

class PaletteTargetMaster {
  final double saturationWeight;
  final double lightnessWeight;
  final double populationWeight;
  final double minimumSaturation;
  final double maximumSaturation;
  final double targetSaturation;
  final double minimumLightness;
  final double maximumLightness;
  final double targetLightness;
  final bool isExclusive;
  
  // Predefined targets
  static const PaletteTargetMaster vibrant;
  static const PaletteTargetMaster lightVibrant;
  static const PaletteTargetMaster darkVibrant;
  static const PaletteTargetMaster muted;
  static const PaletteTargetMaster lightMuted;
  static const PaletteTargetMaster darkMuted;
  static const List<PaletteTargetMaster> baseTargets;
}

EncodedImageMaster #

Container for encoded image data.

class EncodedImageMaster {
  const EncodedImageMaster(
    ByteData byteData, {
    required int width,
    required int height,
    ImageByteFormat format = ImageByteFormat.rawRgba,
    String? name,
  });
  
  final ByteData byteData;
  final int width;
  final int height;
  final ImageByteFormat format;
  final String? name;
  
  int get pixelCount;
  double get aspectRatio;
}

ColorHarmonyMaster #

Represents a color harmony scheme.

class ColorHarmonyMaster {
  const ColorHarmonyMaster(HarmonyType type, List<Color> colors);
  
  final HarmonyType type;
  final List<Color> colors;
  
  static List<ColorHarmonyMaster> generateHarmonyColors(Color base);
}

HarmonyType #

enum HarmonyType { 
  complementary,    // 180° apart
  triadic,         // 120° apart
  analogous,       // 30° apart
  splitComplementary  // Base + complement neighbors
}

AccessibilityHelperMaster #

Static utility class for accessibility features.

class AccessibilityHelperMaster {
  static Color getBestTextColor(Color background);
  static bool meetsWcagAA(double contrastRatio, {bool isLargeText = false});
  static bool meetsWcagAAA(double contrastRatio, {bool isLargeText = false});
  static double calculateContrastRatio(Color foreground, Color background);
  static List<AccessibleColorPair> generateAccessiblePairs(
    List<PaletteColorMaster> colors, {
    double minimumContrast = 4.5
  });
}

AccessibleColorPair #

Represents a pair of colors with contrast information.

class AccessibleColorPair {
  const AccessibleColorPair(Color foreground, Color background, double contrastRatio);
  
  final Color foreground;
  final Color background;
  final double contrastRatio;
  
  bool get meetsWcagAA;
  bool get meetsWcagAAA;
  bool get meetsWcagAALarge;
  bool get meetsWcagAAALarge;
}

🎨 Color Spaces #

RGB (Red, Green, Blue) #

Best for: General purpose, web colors
Characteristics: Device-dependent, intuitive for developers
Use when: Working with standard web/mobile colors

HSV (Hue, Saturation, Value) #

Best for: Color manipulation, artistic applications
Characteristics: More intuitive for humans, easier color adjustments
Use when: Need to adjust brightness/saturation programmatically

LAB (Lightness, A, B) #

Best for: Perceptually uniform color analysis
Characteristics: Device-independent, perceptually uniform
Use when: Need most accurate color analysis (recommended)

♿ Accessibility Guidelines #

This package follows WCAG 2.1 guidelines:

Contrast Ratios #

AA Level: 4.5:1 for normal text, 3:1 for large text
AAA Level: 7:1 for normal text, 4.5:1 for large text

Usage Examples #

// Check if colors meet WCAG AA
final bool isAccessible = AccessibilityHelperMaster.meetsWcagAA(
  contrastRatio,
  isLargeText: false,
);

// Generate only AA compliant pairs
final accessiblePairs = generator.getAccessibleColorPairs(
  minimumContrast: 4.5,
);

// Get best text color with custom logic
final textColor = generator.getBestTextColorFor(backgroundColor);

🔄 Migration from palette_generator #

If you're migrating from the discontinued palette_generator package:

Class Name Changes #

Old Class	New Class
`PaletteGenerator`	`PaletteGeneratorMaster`
`PaletteColor`	`PaletteColorMaster`
`PaletteTarget`	`PaletteTargetMaster`
`EncodedImage`	`EncodedImageMaster`

API Changes #

// Old way
final PaletteGenerator generator = await PaletteGenerator.fromImageProvider(
  AssetImage('image.jpg'),
);

// New way
final PaletteGeneratorMaster generator = await PaletteGeneratorMaster.fromImageProvider(
  AssetImage('image.jpg'),
  generateHarmony: true,      // New: harmony generation
);

Property Changes #

// Old
Color? dominantColor = generator.dominantColor;

// New
PaletteColorMaster? dominant = generator.dominantColor;
Color? dominantColor = generator.dominantColor?.color;

New Features Not in Original #

Multi-color space support (RGB, HSV, LAB)
Accessibility features and WCAG compliance
Color harmony generation with 4 different schemes
Enhanced performance and accuracy with 5-bit quantization
Modern null-safe API
Region-based processing
Custom filters support
Timeout handling for network images

📱 Example App #

The package includes a comprehensive example app that demonstrates all features:

Interactive color space selection
Real-time accessibility information
Color harmony visualization
Detailed color information with copy-to-clipboard
Modern Material 3 design
Image picker integration
Custom target configuration

To run the example:

cd example
flutter run

⚡ Performance Tips #

Use appropriate color space: RGB for speed, LAB for accuracy
Limit maximum colors: 16 colors usually sufficient for most use cases
Use region parameter: Process only relevant parts of large images
Use filters: Filter out unwanted colors early in the process
Cache results: Store generated palettes for reuse
Adjust sampling rate: The package uses step 2 sampling by default for balance

// Optimized for performance
final generator = await PaletteGeneratorMaster.fromImageProvider(
  imageProvider,
  maximumColorCount: 12,     // Reasonable limit
  generateHarmony: false,     // Skip if not needed
  filters: [avoidRedBlackWhitePaletteFilterMaster], // Filter unwanted colors
);

// Optimized for accuracy
final generator = await PaletteGeneratorMaster.fromImageProvider(
  imageProvider,
  maximumColorCount: 24,
  generateHarmony: true,
  colorSpace: ColorSpace.lab, // Most accurate
);

// Cache the result
final cachedGenerator = generator;

🐛 Troubleshooting #

Common Issues #

Q: Colors look different than expected A: Try using LAB color space for more perceptually accurate results.

final generator = await PaletteGeneratorMaster.fromImageProvider(
  imageProvider,
  colorSpace: ColorSpace.lab,
);

Q: Performance is slow A: Reduce maximumColorCount or use RGB color space instead of LAB.

final generator = await PaletteGeneratorMaster.fromImageProvider(
  imageProvider,
  maximumColorCount: 8,
  colorSpace: ColorSpace.rgb,
);

Q: Not getting vibrant colors A: Adjust the target parameters or use a custom PaletteTargetMaster.

final customVibrant = PaletteTargetMaster(
  minimumSaturation: 0.5,
  targetSaturation: 0.8,
  saturationWeight: 0.7,
  // ... other parameters
);

Q: Accessibility pairs are empty A: Lower the minimumContrast threshold or ensure your image has sufficient color variety.

final pairs = generator.getAccessibleColorPairs(
  minimumContrast: 3.0, // Lower threshold
);

Q: Network images timeout A: Increase the timeout duration for large images or slow connections.

final generator = await PaletteGeneratorMaster.fromImageProvider(
  NetworkImage('https://example.com/large-image.jpg'),
  timeout: Duration(seconds: 30),
);

Q: Memory issues with large images A: Use region parameter to process only a portion of the image.

final generator = await PaletteGeneratorMaster.fromImageProvider(
  imageProvider,
  region: Rect.fromLTWH(0, 0, 500, 500),
  maximumColorCount: 12,
);

📄 License #

This package is licensed under the BSD 3-Clause License. See the LICENSE file for details.

🙏 Acknowledgements #

Original palette_generator package authors
Android Palette API for inspiration
WCAG guidelines documentation
Flutter community for feedback and contributions

📞 Support #

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@palettegenerator.dev

🤝 Contributing #

Contributions are welcome! Please read our Contributing Guide for details.

DME is written in clear, professional English with proper formatting and structure suitable for pub.dev publication.

palette_generator_master 1.1.0 palette_generator_master: ^1.1.0 copied to clipboard

Metadata