🌐 Progress Sphere

NucleoSphere 3D Progress Visualization
Version 2026Q1 | Updated January 8, 2026

🌐 Overview

The NucleoSphere is a 3D progress indicator featuring up to 8 concentric translucent spherical shells with a cutaway quadrant. Progress is represented by rotating the entire assembly around the Z-axis.

💡
Design Concept: The sphere is automatically sized relative to model extents and positioned at one of 5 configurable locations. The cutaway reveals internal colored layers, and rotation indicates completion (0° = 0%, 360° = 100%).

Key Features

  • Up to 8 concentric semi-transparent shells
  • Date-based event colors (Pride Month, Halloween, etc.) or default grayscale
  • Auto-sized based on model extents (configurable percentage)
  • 5 position modes for overlay display
  • Configurable transparency
  • INI file control for enabling/disabling event colors

🎨 Event-Based Color System

The NucleoSphere automatically changes colors based on the current date. Events are defined in language-specific configuration files that are checked at initialization.

INI File Control

The event color system is controlled via the project INI file entry fxNucleoEventColors:

INI Entry Value Behavior
fxNucleoEventColors 1 (default) Auto - use event colors when current date matches an event window
fxNucleoEventColors 0 Disabled - always use default grayscale (8 shades from dark to light)
fxNucleoEventColors -1 Demo mode - cycle through ALL events sequentially (for testing)
⚙️
To Disable Event Colors: Add the following line to your project INI file:
fxNucleoEventColors,0

Configuration Files

Event colors are defined in language-specific files located in the fixture support folder:

File Language Notes
fxNucleoEvents.034 Spanish Localized event names
fxNucleoEvents.044 English Default fallback if localized file not found
fxNucleoEvents.049 German Localized event names
fxNucleoEvents.055 Portuguese Localized event names

Config File Format

# Comment lines start with # # Format: START_MMDD,END_MMDD,EVENT_NAME,R1,G1,B1,R2,G2,B2[,R3,G3,B3...] # Dates in MM-DD format (year-independent, events repeat annually) # Colors cycle to fill all 8 shells (2 colors = alternating pattern) 06-01,06-30,Pride Month,255,0,0,255,127,0,255,255,0,0,255,0,0,0,255,139,0,255 10-24,11-07,Halloween,255,117,24,25,25,25 01-21,02-20,Lunar New Year,238,28,37,255,215,0

Pre-Configured Events (fxNucleoEvents.044)

Event Date Range Colors
Lunar New Year Jan 21 - Feb 20
Saint David's Day Feb 27 - Mar 6
St. Patrick's Day Mar 10 - Mar 24
St. George's Day Mar 20 - Mar 31
Earth Day Apr 15 - Apr 29
Pride Month Jun 1 - Jun 30
Independence Day (US) Jun 27 - Jul 11
Diwali Oct 15 - Nov 15
Halloween Oct 24 - Nov 7
Remembrance Day Nov 4 - Nov 18
St. Andrew's Day Nov 25 - Dec 2
📁
User Customization (Planned): Copy the event file to a public folder (e.g., C:\SolidCut_Data\config\) to customize without admin access. The public version takes precedence if it exists.
🎉
Adding Custom Events: Edit the appropriate fxNucleoEvents.XXX file to add your own events. Use MM-DD format for dates - events repeat annually without needing updates.

📍 Position Modes

The sphere can be positioned at 5 different locations relative to the model bounding box. All positions are at the top of the model (maxZ + offset) to stay visible and out of the way.

Mode Name X Position Y Position Z Position
0 Centre Model centre X Model centre Y Top (maxZ + offset)
1 Top-Left (default) Left (minX - offset) Front (minY - offset) Top (maxZ + offset)
2 Top-Right Right (maxX + offset) Front (minY - offset) Top (maxZ + offset)
3 Back-Left Left (minX - offset) Back (maxY + offset) Top (maxZ + offset)
4 Back-Right Right (maxX + offset) Back (maxY + offset) Top (maxZ + offset)
POSITION MODE LAYOUT (Top-Down View, looking at -Z) FRONT (minY) ┌─────────┬─────────┐ │ 1 │ 2 │ ← Front corners (modes 1, 2) │ Top-Left│Top-Right│ ├─────────┼─────────┤ │ │ │ │ ┌────┴────┐ │ │ │ MODEL │ │ │ │ 0 │ │ ← Centre (mode 0) - directly above │ │ Centre │ │ │ └────┬────┘ │ │ │ │ ├─────────┼─────────┤ │ 3 │ 4 │ ← Back corners (modes 3, 4) │Back-Left│Back-Rght│ └─────────┴─────────┘ BACK (maxY) All positions at same Z height (above model top) Offset = radius × 1.5 (so sphere doesn't touch model)

⚙️ Configuration

Global Variables (fxGlobals.var)

Variable Type Description Default
w_FX_NUCLEO_RADIUS_PERCENT Float Sphere radius as percentage of model size 0.10 (10%)
i_FX_NUCLEO_TRANSPARENCY Integer Shell transparency (0=opaque, 100=invisible) 50
i_FX_NUCLEO_DISPLAY_MODE Integer 0=overlay on model, 1=isolated at origin 0
i_FX_NUCLEO_POSITION_MODE Integer Position mode 0-4 (see table above) 1 (Top-Left)

Event Color Output Globals

These are set by fxNucleoEventColors and read by fxNucleoSphere:

Variable Description
i_FX_EVENT_ACTIVE 1 if an event is active, 0 otherwise
i_FX_EVENT_COLOR_COUNT Number of unique colors defined for the event
i_FX_EVENT_R(8) Red values for each shell (0-255)
i_FX_EVENT_G(8) Green values for each shell (0-255)
i_FX_EVENT_B(8) Blue values for each shell (0-255)
$_FX_EVENT_NAME Name of the active event (for display/logging)
i_FX_EVENT_DEMO_INDEX Demo mode counter - cycles through events sequentially

GUI Control Flags

These control progress display in headless/batch modes:

Variable Description Default
i_FX_HIDDEN_GUI 1=headless/batch mode, suppresses all GUI 0
i_FX_SHOW_PROGRESS 1=show NucleoSphere progress, 0=skip 1
i_FX_MINIMAL_OVERHEAD 1=maximum speed, skip all visuals 0

📋 Syntax

call fxNucleoSphere w_progress w_radius i_shellCount w_lastRotation [i_displayMode] [i_positionMode]

Parameters:
  w_progress     - Progress 0-100, -1=initialize, i_NOT_SET=cleanup
  w_radius       - Sphere radius (auto-calculated in overlay mode, use i_NOT_SET)
  i_shellCount   - Number of shells (default 8)
  w_lastRotation - Previous rotation angle (for incremental updates)
  i_displayMode  - 0=overlay (default), 1=isolated at origin
  i_positionMode - 0-4 position mode (see table above)

Returns:
  i_return - Shell count
  w_return - Current progress value

Color Control:
  Colors are automatically determined by fxNucleoEventColors based on:
  - Current date (matches event windows in fxNucleoEvents.XXX files)
  - INI setting: fxNucleoEventColors = 1 (auto), 0 (disabled), -1 (demo)

💻 Usage Example

'*** Initialize sphere at top-right corner (mode 2), 8 shells
call fxNucleoSphere -1 i_NOT_SET 8 i_FALSE i_FALSE 2
i_shellCount = i_return
w_lastProgress = i_FALSE

'*** Update progress in a loop
for i_step = 1 to 100
   call fxNucleoSphere i_step i_NOT_SET i_shellCount w_lastProgress i_FALSE 2
   w_lastProgress = w_return
   
   '*** ... do actual work here ...
   
next i_step

'*** Cleanup when done
call fxNucleoSphere i_NOT_SET i_NOT_SET i_shellCount w_lastProgress i_FALSE 2
✓
Best Practice: Always store w_return as w_lastProgress and pass it back on the next call. This enables smooth incremental rotation rather than jumping.

Using the Progress Wrapper

For most use cases, use fxProgressUpdate which handles GUI state and provides a simpler interface:

'*** Initialize
call fxProgressUpdate -1 9

'*** Update progress (steps 1-9)
for i_step = 1 to 9
   call fxProgressUpdate i_step 9
   '*** ... do work ...
next i_step

'*** Cleanup
call fxProgressUpdate i_NOT_SET 9

🔧 Technical Details

Rotation Strategy

  1. Sphere is created at origin (0, 0, 0)
  2. After creation, translated to display position
  3. Each rotation cycle:
    1. Translate back to origin
    2. Rotate around Z-axis
    3. Translate to display position

Color Determination Flow

fxNucleoSphere init (-1) │ ▼ call fxNucleoEventColors │ ├─► Read INI: fxNucleoEventColors │ │ │ ├─ 0 → Return (use grayscale) │ ├─ 1 → Check date against events │ └─ -1 → Demo mode (cycle all events) │ ├─► Load language-specific config file │ (falls back to .044 if not found) │ ├─► Parse events, check date match │ └─► Set i_FX_EVENT_R/G/B(1-8) arrays fxNucleoSphere reads arrays and applies colors

Files

File Purpose
fxNucleoSphere.ovm Main sphere creation, rotation, and cleanup
fxNucleoEventColors.ovm Date-based event color loader
fxProgressUpdate.ovm Wrapper with GUI control flags
fxTestProgressHandler.ovm Test harness cycling through all position modes
fxNucleoEvents.044 English event configuration
fxNucleoEvents.034/.049/.055 Localized event configurations
fxGlobals.var Global configuration variables