Sphere10.Framework.Drawing 3.1.1

🎨 Sphere10.Framework.Drawing

Unified 2D graphics abstraction layer providing drawing utilities, color manipulation, image processing, and shape rendering for Windows desktop and cross-platform applications.

Color and rectangle geometry helpers can be used across platforms. Image, icon, graphics-path, codec, and GDI+ drawing operations depend on Windows through System.Drawing.Common and declare that requirement with SupportedOSPlatform attributes. Image-header detection handles streams that return fewer bytes per read.

📦 Installation

dotnet add package Sphere10.Framework.Drawing

⚡ 10-Second Example

using Sphere10.Framework;
using System.Drawing;

// Create color gradient
Color[] gradient = Tools.Drawing.CalculateColorGradient(
    Color.Red, 
    Color.Blue, 
    10);  // 10 colors from red to blue

foreach (var color in gradient) {
    Console.WriteLine($"RGB({color.R}, {color.G}, {color.B})");
}

// Convert string to color
Color myColor = Tools.Drawing.ConvertStringToColor("255:0:128");

// Manipulate images
Bitmap image = new Bitmap("photo.jpg");
Bitmap rounded = Tools.Drawing.CreateRoundedImage(image, 20);  // 20px radius
rounded.Save("rounded.jpg");

🏗️ Core Concepts

Color Gradients: Smooth color transitions between start and end colors with interpolation.

Color Conversions: Parse and convert between string, ARGB, and Color representations.

Image Processing: Bitmap manipulation including resizing, rounding corners, and visual effects.

Geometric Utilities: Point, size, and rectangle extensions for calculations.

Rounded Corners: Create images with smooth rounded corners and borders.

🔧 Core Examples

Color Gradient Generation

using Sphere10.Framework;
using System.Drawing;

// Generate gradient with interpolation between two colors
Color startColor = Color.FromArgb(255, 0, 0);      // Red
Color endColor = Color.FromArgb(0, 0, 255);        // Blue
int gradientSteps = 20;

Color[] gradient = Tools.Drawing.CalculateColorGradient(
    startColor, 
    endColor, 
    gradientSteps);

Console.WriteLine($"Generated {gradient.Length} colors:");
for (int i = 0; i < gradient.Length; i++) {
    Console.WriteLine($"  [{i}] ARGB({gradient[i].A}, {gradient[i].R}, {gradient[i].G}, {gradient[i].B})");
}

// Use gradient for visual effects
// For example, painting a gradient fill:
using (var brush = new LinearGradientBrush(
    new Point(0, 0), 
    new Point(256, 0), 
    startColor, 
    endColor)) {
    
    graphics.FillRectangle(brush, new Rectangle(0, 0, 256, 50));
}

String to Color Conversion

using Sphere10.Framework;
using System.Drawing;

// Convert string formats to Color
string[] colorStrings = {
    "255:0:0",              // Red (RGB)
    "0:255:0",              // Green (RGB)
    "0:0:255",              // Blue (RGB)
    "255:128:64:200"        // With Alpha (ARGB)
};

foreach (var colorStr in colorStrings) {
    Color color = Tools.Drawing.ConvertStringToColor(colorStr);
    Console.WriteLine($"{colorStr} -> ARGB({color.A}, {color.R}, {color.G}, {color.B})");
}

// Round-trip conversion
Color original = Color.FromArgb(200, 100, 150, 50);
string colorString = $"{original.A}:{original.R}:{original.G}:{original.B}";
Color converted = Tools.Drawing.ConvertStringToColor(colorString);
Console.WriteLine($"Match: {original == converted}");  // true

Image Rounding & Corner Effects

using Sphere10.Framework;
using System.Drawing;

// Load and process image
Bitmap originalImage = new Bitmap("photo.jpg");

// Create rounded corners
int cornerRadius = 30;
Bitmap roundedImage = Tools.Drawing.CreateRoundedImage(originalImage, cornerRadius);
roundedImage.Save("rounded_photo.jpg");

// Create rounded image with border
Bitmap borderedImage = Tools.Drawing.CreateRoundedImage(
    originalImage, 
    cornerRadius, 
    5,              // Border width
    Color.DarkGray);// Border color

borderedImage.Save("rounded_with_border.jpg");

// Create circular image (max corner radius)
int maxRadius = Math.Min(originalImage.Width, originalImage.Height) / 2;
Bitmap circularImage = Tools.Drawing.CreateRoundedImage(originalImage, maxRadius);
circularImage.Save("circular_photo.jpg");

Image Resizing & Scaling

using Sphere10.Framework;
using System.Drawing;

Bitmap original = new Bitmap("large_image.jpg");

// Resize to specific dimensions
Size newSize = new Size(400, 300);
Bitmap resized = Tools.Drawing.ResizeImage(original, newSize, ResizeMethod.HighQuality);
resized.Save("resized.jpg");

// Scale by percentage
Bitmap scaled = Tools.Drawing.ScaleImage(original, 0.5);  // 50% of original
scaled.Save("scaled_50percent.jpg");

// Maintain aspect ratio while fitting in bounds
Size maxBounds = new Size(800, 600);
Bitmap fitted = Tools.Drawing.FitImageInBounds(original, maxBounds);
fitted.Save("fitted.jpg");

Point & Rectangle Extensions

using Sphere10.Framework;
using System.Drawing;

// Point calculations
Point p1 = new Point(10, 20);
Point p2 = new Point(30, 40);

// Distance between points
double distance = p1.DistanceTo(p2);
Console.WriteLine($"Distance: {distance}");

// Offset point
Point offset = p1.Offset(5, 10);
Console.WriteLine($"Offset: {offset}");  // (15, 30)

// Rectangle operations
Rectangle rect = new Rectangle(10, 10, 100, 100);
Point center = rect.GetCenter();
Console.WriteLine($"Center: {center}");  // (60, 60)

// Check containment with margin
bool contains = rect.ContainsWithMargin(new Point(50, 50), 5);

// Get area
int area = rect.GetArea();
Console.WriteLine($"Area: {area}");  // 10000

// Expand rectangle
Rectangle expanded = rect.Expand(20);  // Expand by 20px on all sides
Console.WriteLine($"Expanded: {expanded}");

Disabled/Grayed-Out Effects

using Sphere10.Framework;
using System.Drawing;

Bitmap originalImage = new Bitmap("icon.png");

// Create disabled (grayed-out) version
Bitmap disabledImage = Tools.Drawing.CreateDisabledImage(originalImage);
disabledImage.Save("icon_disabled.png");

// This is useful for UI states like:
// - Inactive buttons
// - Disabled menu items
// - Inactive toolbar icons

Size & Scaling Extensions

using Sphere10.Framework;
using System.Drawing;

Size original = new Size(800, 600);

// Scale size
Size scaled = original.Scale(1.5);  // 1200 x 900
Console.WriteLine($"Scaled: {scaled}");

// Get aspect ratio
float ratio = original.GetAspectRatio();  // 1.333...
Console.WriteLine($"Aspect Ratio: {ratio}");

// Fit within bounds maintaining aspect
Size maxBounds = new Size(400, 400);
Size fitted = original.FitWithinBounds(maxBounds);
Console.WriteLine($"Fitted: {fitted}");

// Create thumbnail
Size thumb = original.CreateThumbnailSize(150);
Console.WriteLine($"Thumbnail: {thumb}");

🏗️ Architecture & Modules

Color Module: Color conversion, gradients, and color space operations

• String parsing (ARGB format)
• RGB ↔ HSL conversions
• Color space transformations
• Gradient interpolation

Image Processing Module: Bitmap operations and effects

• Resizing with quality control
• Rounded corners and borders
• Disabled/grayed-out effects
• Aspect ratio preservation

Geometric Utilities: Point, Size, Rectangle extensions

• Distance calculations
• Containment testing
• Area and perimeter operations
• Center point calculation
• Alignment and positioning

Drawing Extensions: System.Drawing extensions

• Graphics primitives
• Brush and pen utilities
• Text rendering helpers
• Bitmap manipulation

📦 Dependencies

• Sphere10 Framework: Core framework
• System.Drawing.Common: Windows image loading and GDI+ drawing APIs, supplied as a NuGet package
• System.Drawing.Primitives: Primitive types (Point, Size, Rectangle)

⚠️ Best Practices

• Dispose resources: Always dispose Bitmap, Graphics, and Brush objects
• Quality vs performance: Use HighQuality resize for final output; LowQuality for previews
• Color validation: Validate color strings before conversion
• Image size limits: Check image dimensions before processing to avoid memory issues
• Use using statements: Wrap Graphics operations in using blocks
• Cache gradients: Pre-calculate gradients if used repeatedly

✅ Status & Compatibility

• Maturity: Production-tested, stable for desktop applications
• .NET Target: .NET 10 (net10.0)
• Platform Support: Color and geometry helpers are cross-platform; image loading and GDI+ drawing require Windows, including with System.Drawing.Common 11.
• Performance: Resizing is CPU-intensive; cache results when possible

📖 Related Projects

• Sphere10.Framework - Core framework
• Sphere10.Framework.Windows.Forms - WinForms integration with drawing support
• Sphere10.Framework.Windows - Windows-specific graphics APIs

⚖️ License

Distributed under the MIT NON-AI License.

See the LICENSE file for full details. More information: Sphere10 NON-AI-MIT License

👤 Author

Herman Schoenfeld - Software Engineer