# Copyright (c) 2025-2026 Gigasoft, Inc. All rights reserved.
=== ProEssentials Pe3do (knowledge rev 4.1) (3D Scientific Graph) Patterns ===

Pe3do is the 3D Scientific Graph Object. It renders surfaces, 3D bars,
scatter plots, waterfalls, and contour maps using X, Y, Z data arrays
and Direct3D rendering. ALWAYS query pe_query.py for exact paths.

POLYMODE + PLOTTINGMETHOD (the two-level dispatch system):
  Pe3do chart type is determined by TWO properties together.
  PolyMode selects the CHART CATEGORY.
  PlottingMethod selects the RENDERING VARIANT within that category.
  PlottingMethod meaning CHANGES depending on PolyMode.

  PePlot.PolyMode -- set FIRST for non-surface charts:
    SurfacePolygons (1) -- default, grid data --> surface mesh
    ThreeDBar (2) -- grid data --> one bar per cell
    PolygonData (3) -- raw polygon vertices --> custom 3D shapes
    Scatter (4) -- XYZ points --> scatter, lines, or waterfall

  PePlot.Method = ThreeDGraphPlottingMethod enum:
  WARNING: Pe3do uses ThreeDGraphPlottingMethod (NOT GraphPlottingMethod).

  For SurfacePolygons, ThreeDBar, PolygonData:
    0 = WireFrame
    1 = Surface
    2 = Surface with Shading
    3 = Surface with Pixels
    4 = Surface with Contours (SurfacePolygons ONLY, not Bar/Polygon)

  For Scatter:
    0 = Points
    1 = Lines
    2 = Points + Lines
    3 = Area (waterfall slices)

DATA STRUCTURE:
  PeData.Subsets x PeData.Points -- grid dimensions
  PeData.X[s,p] -- X coordinate (horizontal)
  PeData.Y[s,p] -- Y coordinate (vertical, the "value" axis)
  PeData.Z[s,p] -- Z coordinate (depth)
  PeString.SubsetLabels[s] -- Z-axis labels
  PeString.PointLabels[p] -- X-axis labels
  Large datasets: use PeData.X.FastCopyFrom(array, count) for performance.

DUPLICATEDATA OPTIMIZATION (large uniform grids):
  When all subsets share the same X values (uniform grid), avoid passing
  full X[s,p] arrays. Instead pass a single row and set:
    PeData.DuplicateDataX = DuplicateData.PointIncrement;
    PeData.DuplicateDataZ = DuplicateData.SubsetIncrement;
  Then FastCopyFrom X with nPoints values, Z with nSubsets values,
  and Y with the full nSubsets*nPoints values.
  Set DuplicateData properties BEFORE calling FastCopyFrom.
  Saves memory and data transfer -- no change in behavior.
  See Example 408 (large surface with 1001x1001 grid).

WATERFALL PATTERN (PolyMode=Scatter + Method=Area):
  A waterfall plot is Scatter mode with area rendering:
    PePlot.PolyMode = PolyMode.Scatter;
    PePlot.Method = ThreeDGraphPlottingMethod.Three;  // Area
  Then layer waterfall-specific properties:
    PePlot.Option.WaterfallContours = true;  -- contour-color the slices
    PePlot.Option.WaterfallBorders = true;   -- draw borders on slices
    PeColor.BarBorderColor = Color...;       -- border color
    PeColor.ContourColorSet = ContourColorSet.BlueCyanGreen...;
    PeColor.ContourColorBlends = 20;         -- interpolation steps
    PeColor.ContourColorAlpha = 255;         -- affects lines/points only,
      NOT the area fill. WaterfallContours overrides area coloring.
  SubsetLineTypes per subset control slice edge rendering.
  See Example 407.

DELAUNAY TRIANGULATION (point cloud --> surface):
  A boolean toggle on default surface mode -- NOT a separate PolyMode:
    PePlot.Option.Delaunay3D = true;
    PePlot.Method = ThreeDGraphPlottingMethod.Four;  // Surface+Contour
    PeData.Subsets = 1;       -- always 1 subset
    PeData.Points = N;        -- flat list of XYZ points
  The engine triangulates the XZ plane, uses Y as height.
  Combine with contour coloring (see below). See Example 414.

THREE CONTOUR COLORING APPROACHES:
  A) SubsetColors as contour bands (most control):
    Manually set 60-100 SubsetColors to define gradient bands.
    Set PeLegend.ContourStyle = true. See Example 408.

  B) Predefined ContourColorSet:
    PeColor.ContourColorSet = ContourColorSet.BlueCyanGreenYellowBrownWhite;
    PeColor.ContourColorBlends = N;  -- interpolation between colors
    See Example 407 (waterfall).

  C) Custom ContourColors array:
    PeColor.ContourColors.Clear(N);  -- set array size
    PeColor.ContourColors[0..N] = Color...;  -- define gradient stops
    PeColor.ContourColorSet = ContourColorSet.ContourColors;  -- activate
    PeColor.ContourColorBlends = N;  -- interpolation between stops
    See Example 414 (Delaunay).

  Manual contour range control (PE3DO ONLY -- not available on Pesgo):
    Pe3do1.PePlot.Option.ManualContourScaleControl = ManualScaleControl.MinMax;
    Pe3do1.PePlot.Option.ManualContourMin = 80.0F;
    Pe3do1.PePlot.Option.ManualContourMax = 102.0F;
    For Pesgo contour Z-range clamping, use PeGrid.Configure instead:
      PeGrid.Configure.ManualScaleControlZ = ManualScaleControl.MinMax;
      PeGrid.Configure.ManualMinZ / ManualMaxZ
    See pe-pesgo-patterns for Pesgo contour details.

  CUSTOM CONTOUR COLORING VIA SUBSETCOLORS (preferred method):
    For full control over 3D surface contour colors, manually define
    SubsetColors to set exact color bands. Same approach as Pesgo contour.
    Pattern:
      1. Define N SubsetColors entries -- each maps to one contour band
      2. Define matching SubsetShades for contour line colors
      3. Colors distribute evenly across the Y-range (auto or manual)
    BEST PRACTICE -- Anchor-point interpolation: When you need a smooth
    gradient across many bands, define anchor colors at key value thresholds
    and linearly interpolate RGB between anchors. Produces smooth,
    professional color ramps with precise control at critical thresholds.
    After setting SubsetColors in Direct3D mode:
      Pe3do1.PeFunction.Force3dxNewColors = true;
      Pe3do1.PeFunction.Force3dxVerticeRebuild = true;

POLYGON DATA (custom 3D geometry):
  PolyMode.PolygonData enables raw polygon rendering:
    PePlot.PolyMode = PolyMode.PolygonData;
  Define PolygonData structs with vertices (3 or 4 per polygon) and
  per-polygon colors, then pass via PEvsetW to PeSpecial.HObject.
  Axes are typically hidden (ShowXAxis/ShowYAxis/ShowZAxis = Empty).
  Somewhat rare but used for custom 3D shapes (spheres, objects).
  GraphAnnotation also supports polygon data for 3D shape annotations.
  See Example 406 (sphere from terrain data).

CAMERA AND VIEWING:
  PeUserInterface.Scrollbar.ViewingHeight -- camera elevation (0--36)
  PeUserInterface.Scrollbar.DegreeOfRotation -- rotation angle (0--359)
  PePlot.Option.DxZoom -- initial zoom level (negative = zoomed out)
  PePlot.Option.DxZoomMax / DxZoomMin -- zoom limits for mouse wheel
  PePlot.Option.DxViewportPanFactor -- shift+drag sensitivity
  PePlot.Option.DxViewportX/Y -- viewport translation
  PePlot.Option.DxFitControlShape -- auto-fit to control shape

ISOMETRIC PERSPECTIVE (DxFOV):
  PePlot.Option.DxFOV -- default 1 (45-degree FOV, strong perspective).
  Set 8-10 for near-isometric view. FOV = Pi/(4*DxFOV). Setting this
  auto-adjusts DxZoom; use DegreePrompting to tune. See Example 404.

LIGHTING:
  Pe3do1.PeFunction.SetLight(index, x, y, z) -- position a light source
  PePlot.Option.LightStrength -- light intensity (0.0--1.0, e.g., 0.65)
  Different chart types benefit from different light positions:
    Surface: SetLight(0, 1.5, -1.5, 2.0)
    3D Bar:  SetLight(0, 4.6, 0.8, 9.5)

SMOOTH INTERACTION:
  PeUserInterface.Scrollbar.ScrollSmoothness -- rotation smoothness (1--6)
  PeUserInterface.Scrollbar.MouseWheelZoomSmoothness -- zoom smoothness
  PeUserInterface.Scrollbar.PinchZoomSmoothness -- touch zoom smoothness
  PeUserInterface.Scrollbar.MouseWheelZoomFactor -- zoom sensitivity
  PeUserInterface.Scrollbar.MouseDraggingX/Y = true -- enable drag rotate

SURFACE-SPECIFIC PROPERTIES:
  PePlot.Allow.WireFrame -- enable/disable wireframe toggle
  PePlot.Option.ShowContour -- contour display (ShowContour enum)
  PeLegend.ContourStyle = true -- show contour legend
  PeLegend.ContourLegendPrecision -- decimal places in legend
  PeColor.SubsetColors[(int)SurfaceColors.WireFrame] -- wireframe color
  PeColor.SubsetColors[(int)SurfaceColors.SolidSurface] -- surface color
  PeGrid.Configure.DxPsManualCullXZ = true -- enables pixel shader culling
    when ManualScaleControlX/Z restrict the visible range. Without this,
    all triangles render even when zoomed via manual axis limits. Essential
    when driving Pe3do zoom from an external source (e.g., 2D contour zoom).

GRID ASPECT:
  PeGrid.Option.GridAspectX/Y/Z -- stretch factor per axis (default 1.0)
  Values > 1.0 stretch that axis. GridAspectY = 0.5 compresses height.

SEMI-TRANSPARENT BARS:
  SubsetColors with alpha < 255 create see-through 3D bars.
  Example: Color.FromArgb(216, 0, 148, 0) -- helps see bars behind.

LEGEND FOR 3D BAR CHARTS:
  Pe3do does NOT produce a standard subset legend in Surface, ThreeDBar,
  or PolygonData modes. Only Scatter mode generates a native subset legend.
  Two workarounds provide legend functionality for 3D Bar charts:

  TECHNIQUE A -- ContourLegendII (color-bar legend):
    Use the secondary contour legend as a standalone color-to-value legend.
    It is independent of the main legend system and renders regardless of
    PolyMode. Define SubsetColors on ContourLegendII to match your bar
    colors, set the numeric range, and you get a visual legend bar.
      PeLegend.ContourLegendII.ShowContourLegend = ShowContourLegendII.SecondOnly;
      PeLegend.ContourLegendII.ManualContourScaleControl = ManualScaleControl.MinMax;
      PeLegend.ContourLegendII.ManualContourMin = minValue;
      PeLegend.ContourLegendII.ManualContourMax = maxValue;
      PeLegend.ContourLegendII.SubsetColors[i] = matchingBarColor;
      PeLegend.ContourLegendII.ContourLegendTitle = "Values";
    Best for: continuous value ranges where bars represent magnitude.
    See pe-pointcolors knowledge file for ContourLegendII details.

  TECHNIQUE B -- Table Annotation as custom legend:
    Create a table annotation positioned at a chart edge with symbol cells
    (LegendAnnotationType) paired with text labels. Gives full control over
    layout, fonts, colors, and borders.
      PeAnnotation.Table.Working = 0;
      PeAnnotation.Table.Rows = numCategories;
      PeAnnotation.Table.Columns = 2;  // symbol + label
      PeAnnotation.Table.Type[row, 0] = LegendAnnotationType.SquareSolid;
      PeAnnotation.Table.Color[row, 0] = barColor;
      PeAnnotation.Table.Text[row, 1] = "Category Name";
      PeAnnotation.Table.Location = GraphTALocation.TopRight;
      PeAnnotation.Table.Show = true;
    Best for: categorical legends with discrete labels per bar group.
    Supports Moveable = TAMoveable.Full for user-draggable positioning.
    See pe-table-annotations knowledge file for full table annotation details.

SUBTITLE JUSTIFICATION IN Pe3do:
  "||" prefix = right-justified subtitle (used for mouse instructions)
  PeString.MultiSubTitles[0] = second subtitle line
  PePlot.Option.DegreePrompting = true -- shows rotation degrees on screen

RENDER ENGINE (CRITICAL for Pe3do):
  PeConfigure.RenderEngine = RenderEngine.Direct3D -- REQUIRED for Pe3do
  Must set RenderEngine BEFORE QuickStyle for proper 3D initialization.

COMPUTESHADER (Direct3D GPU rendering -- expanded in v10.0.0.24):
  PeData.ComputeShader = true enables GPU-side Direct3D construction.
  Default false (CPU-side construction). Most beneficial for real-time
  high-performance charting; also improves general rendering quality.

  v10.0.0.24 expanded scope to all Pe3do PolyModes that produce surface
  or sample geometry:
    PolyMode = SurfacePolygons -- Surface, Surface Wireframe,
                                  Contoured Surface
    PolyMode = ThreeDBar       -- 3D Bar
    PolyMode = Scatter         -- 3D Scatter Line (thin/medium/thick)
                                  3D Scatter Point (max 8 vertices,
                                    24 indices per symbol due to compute
                                    shader parallelism limits; simpler
                                    symbols use fewer, e.g. up-triangle)
                                  3D Scatter Area / Waterfall
  PolyMode = PolygonData uses CPU-side construction; ComputeShader has
  no effect there.

  HOTSPOTS / REAL-TIME TRADE-OFF:
    The hotspot octree is still built CPU-side on a separate thread after
    the GPU render (250-500ms on large charts). For maximum real-time
    throughput, disable the three properties that trigger hotspot
    construction (all three apply to Pe3do):
      PeUserInterface.HotSpot.Data = false;
      PeUserInterface.Cursor.PromptTracking = false;
      PeUserInterface.Cursor.HighlightColor = Color.FromArgb(0,0,0,0);  // PE empty
    If any of these is active, ComputeShader still runs but the hotspot
    CPU build runs in parallel.

  LINE TYPE CONSTRAINT (Pe3do): under Direct3D, Pe3do supports only solid
  line styles (thin / medium / thick) and tubes via PePlot.LinesOrTubes,
  regardless of ComputeShader. No dash/dot variants on Pe3do. (This
  differs from Pesgo, where ComputeShader unlocks dash and dot styles.)

FINALIZATION SEQUENCE (Pe3do-specific):
  Pe3do1.PeFunction.Force3dxVerticeRebuild = true;
  Pe3do1.PeFunction.Force3dxAnnotVerticeRebuild = true;  // if annotations
  Pe3do1.PeFunction.ReinitializeResetImage();
  Pe3do1.Invalidate();
  Pe3do1.Refresh();  // Pe3do often needs explicit Refresh()

  LIGHTER ALTERNATIVE -- PeFunction.Reinitialize():
    Reinitialize() rebuilds axis scales and layout WITHOUT resetting the
    cached image. Use when changing ManualScaleControl or manual axis limits
    but not data. Follow with Invalidate(). ReinitializeResetImage() is the
    full rebuild (data + image) and remains the standard for data changes.

  PeData.SkipRanging = true -- optimization: skip min/max data scan when
    only axis scales changed (not data). Set before Reinitialize() to avoid
    unnecessary ranging over large datasets. Resets automatically after use.

BASE 400 (CreateSimple3D) PROVIDES:
  10x10 surface data, Method=Zero, Direct3D, surface contour, wireframe,
  DarkNoBorder QuickStyle, BitmapGradientMode, ComputeShader, contour legend,
  medium fonts, mouse dragging, smooth scrolling, data hotspots,
  DegreePrompting, ImageAdjust padding.
  NOTE: Base 400 is surface-oriented. Non-surface types (Bar, Scatter)
  are typically standalone and set all properties from scratch.

4TH DIMENSION WDATA:
  PeData.W[s,p] -- optional 4th data dimension controlling contour color
  independently from Y (height). Setting WData activates it automatically;
  use PeData.W.Clear() to revert. Scale via:
    PeGrid.Configure.ManualScaleControlW = ManualScaleControl.MinMax;
    PeGrid.Configure.ManualMinW / ManualMaxW
  PeString.ContourLegendTitle -- title for contour legend.
  Note: WData does not support ComputeShader. See Example 415.

KEY EXAMPLES:
  400 -- Simple Wire Frame (surface base)
  402 -- Surface with contoured surface
  403 -- Surface with custom polygon colors
  404 -- 3D Scatter Chart (LOG, isometric, DxFOV)
  405 -- 3D Bar Chart (standalone, with 3D box annotations)
  406 -- 3D Polygon Data (sphere from raw polygons)
  407 -- 3D Waterfall Plot (Scatter+Area, contour colored slices)
  408 -- Large Shaded Surface (DuplicateData, 1001x1001 grid)
  410--413 -- Real-Time 3D variants
  414 -- 3D Delaunay Heightmap from Point Cloud
  415 -- 4D Surface with WData
  416 -- 3D Scatter with complex 3D shape annotations