using System; using System.Collections.Generic; using System.Diagnostics; using System.Linq; using System.Threading; using OpenNest.Engine.Jobs.Adapters; using OpenNest.Engine.Jobs.CommonLines; using OpenNest.Engine.Jobs.Cutouts; namespace OpenNest.Engine.Jobs; /// /// One automatic-nesting request: the named engine, the caller's items (drawing, quantity, /// priority, rotation), the stock it may use, and optional job options. Items with a /// nonpositive quantity are skipped. /// public sealed record NestPipelineRequest( string EngineName, IReadOnlyList Items, IReadOnlyList Stock, NestJobOptions Options = null ); /// A proposed layout: new parts bound to caller drawings. PlateIndex is the first /// raw physical occurrence; Quantity is the total physical copies, including the first. public sealed record ProposedPlate(int PlateIndex, NestPlateStock Stock, IReadOnlyList Parts) { /// Common-line groups among ; committing the plate adds them to /// . Empty when the layout has none. public IReadOnlyList CommonLines { get; init; } = Array.Empty(); private int quantity = 1; public int Quantity { get => quantity; init => quantity = value > 0 ? value : throw new ArgumentOutOfRangeException(nameof(Quantity)); } } /// /// The engine's raw result, its independent validation, and the proposed plates. Nothing /// has been committed; the caller decides what to do with an invalid result. /// public sealed class NestPipelineResult { internal NestPipelineResult( string engineName, NestJob job, NestJobResult raw, IReadOnlyList plates, IReadOnlyList violations, bool canKeep, TimeSpan solveTime, TimeSpan validationTime, IReadOnlyDictionary drawingsByPartId, IReadOnlyList unplaced ) { EngineName = engineName; Job = job; Raw = raw; Plates = plates; Violations = violations; CanKeep = canKeep; SolveTime = solveTime; ValidationTime = validationTime; DrawingsByPartId = drawingsByPartId; Unplaced = unplaced; } public string EngineName { get; } public NestJob Job { get; } public NestJobResult Raw { get; } public IReadOnlyList Plates { get; } public IReadOnlyList Violations { get; } public bool IsValid => Violations.Count == 0; /// True when every placement can be represented, even if layout rules fail. /// False for unknown/null requirement IDs or nonfinite poses; Plates is then empty. public bool CanKeep { get; } public NestJobStatus Status => Raw.Status; public NestJobStopReason StopReason => Raw.StopReason; public TimeSpan SolveTime { get; } public TimeSpan ValidationTime { get; } internal IReadOnlyDictionary DrawingsByPartId { get; } /// Every requested copy this proposal leaves unplaced, by requirement and reason, /// counted from the returned placements. Empty when the proposal places every copy; when it /// cannot be kept, all demand is listed as . public IReadOnlyList Unplaced { get; } /// Why a bundled cutout trial was refused before this ordinary solve replaced it; /// empty when no trial ran or the trial was not refused. Never part of : /// the refused trial has no bindable plates. public IReadOnlyList RefusedCutoutTrial { get; private init; } = Array.Empty(); internal NestPipelineResult WithRefusedCutoutTrial(IReadOnlyList refusals) => new(EngineName, Job, Raw, Plates, Violations, CanKeep, SolveTime, ValidationTime, DrawingsByPartId, Unplaced) { RefusedCutoutTrial = refusals }; } /// /// The single automatic-nesting path shared by every front end: build the job, solve it /// with the named engine, validate the result with the benchmark's rules, then bind /// placements to the caller's drawings. The pipeline never mutates caller items, drawings, /// or plates, and it does not care which engine is selected. /// public static class NestPipeline { /// A bundled cutout trial's progress: its commits count proxies, not physical /// parts, so only candidates and plans pass, with no committed counts. internal sealed class PreviewProgress(IProgress inner) : IProgress { public void Report(NestJobProgress value) { if (value != null && value.Stage is NestJobStage.EvaluatingCandidate or NestJobStage.PlanImproved) inner.Report(value with { CommittedPlates = 0, CommittedParts = 0 }); } } /// /// Fills on an engine's plan reports. Parts use /// detached drawings built from the solved job's geometry (bundled cutout frames included), /// one per part, so a preview never touches the caller's drawings or their quantities. /// private sealed class PlanProgress(IProgress inner, NestJob engineJob, IReadOnlyDictionary callerDrawings, CancellationToken token) : IProgress { private readonly Dictionary parts = engineJob.Parts.ToDictionary(p => p.Id, StringComparer.Ordinal); private readonly Dictionary drawings = new(StringComparer.Ordinal); public void Report(NestJobProgress value) { if (value?.Stage == NestJobStage.PlanImproved && value.Plan != null && value.PlanSheets == null) { lock (drawings) { // A plan naming unknown parts has nothing to draw; validation reports it later. if (value.Plan.Plates.Any(s => s.Placements.Any(p => p.PartId == null || !parts.ContainsKey(p.PartId)))) return; value = value with { PlanSheets = PlanSheets(value.Plan, parts, callerDrawings, drawings, token) }; } } inner.Report(value); } } /// /// A plan as displayable sheets: identical sheets once with their count, parts on detached /// drawings built from ' geometry and kept in /// (one per part id), named and colored like the caller's. Every placement must name one of /// . /// internal static IReadOnlyList PlanSheets(NestJobResult plan, IReadOnlyDictionary parts, IReadOnlyDictionary callerDrawings, Dictionary drawings, CancellationToken token) { var sheets = new List(); foreach (var group in RepeatedPlateGrouping.Create(plan.Plates, true, token)) { var placed = new List(group.Sheet.Placements.Count); foreach (var pose in group.Sheet.Placements) { if (!drawings.TryGetValue(pose.PartId, out var drawing)) { drawing = DrawingJobMapper.CreateDrawing(parts[pose.PartId]); // Borrow the caller's name and color for display; bundled frames keep their own. if (callerDrawings.TryGetValue(pose.PartId, out var caller)) { drawing.Name = caller.Name; drawing.Color = caller.Color; } drawings[pose.PartId] = drawing; } // Same pose mapping as NestResultMaterializer: rotate in the snapshot frame, then move. var part = new Part(drawing); part.Rotate(pose.Rotation); part.Location = new Geometry.Vector(pose.X, pose.Y); part.UpdateBounds(); placed.Add(part); } sheets.Add(new ProposedPlate(group.Sheet.PlateIndex, group.Sheet.Stock, placed) { Quantity = group.Quantity, CommonLines = NestResultBinder.BindCommonLines(group.Sheet, placed), }); } return sheets; } /// Resolves through /// ; unknown names throw . /// Engine cancellation propagates unchanged. public static NestPipelineResult Run( NestPipelineRequest request, IProgress progress = null, CancellationToken token = default ) { ArgumentNullException.ThrowIfNull(request); var engine = NestingEngineRegistry.Create(request.EngineName); return Run(engine, request.EngineName, request, progress, token); } /// Runs a caller-supplied engine instance through the same validation and binding. /// Parts that fit other parts' enclosed cutouts are first bundled into their frames /// (engine-agnostic); see . The engine then solves once. /// A bundled trial that fails physical validation, or leaves demand unplaced, is compared /// with an ordinary solve of the same job and the better valid proposal is returned. public static NestPipelineResult Run( INestingEngine engine, string engineName, NestPipelineRequest request, IProgress progress = null, CancellationToken token = default ) => Run(engine, engineName, request, progress, token, cutouts: true); /// The ordinary solve alone, with no cutout pre-pass: a characterization baseline /// for tests and benchmarks, not a front-end setting. internal static NestPipelineResult RunWithoutCutouts( NestPipelineRequest request, IProgress progress = null, CancellationToken token = default ) => Run(NestingEngineRegistry.Create(request.EngineName), request.EngineName, request, progress, token, cutouts: false); /// The bundled cutout trial alone, without the ordinary-solve comparison, so tests /// can exercise its validation boundary. Jobs without bundles run the ordinary solve. internal static NestPipelineResult RunCutoutTrial( INestingEngine engine, string engineName, NestPipelineRequest request, IProgress progress = null, CancellationToken token = default ) { var (job, drawingsByPartId) = CreateJob(engine, request, token); var prepass = CutoutPipelinePrepass.Prepare(job, token); var result = Evaluate(engine, engineName, job, prepass, drawingsByPartId, progress, token); return prepass != null && result.CanKeep && result.IsValid ? Committed(result, progress, token) : result; } internal static NestPipelineResult RunCutoutTrial( NestPipelineRequest request, IProgress progress = null, CancellationToken token = default ) => RunCutoutTrial(NestingEngineRegistry.Create(request.EngineName), request.EngineName, request, progress, token); private static NestPipelineResult Run( INestingEngine engine, string engineName, NestPipelineRequest request, IProgress progress, CancellationToken token, bool cutouts ) { var (job, drawingsByPartId) = CreateJob(engine, request, token); return Run(engine, engineName, job, drawingsByPartId, progress, token, cutouts); } /// /// The pipeline for an already built job whose part ids map to /// (the benchmark builds its own jobs); identical to otherwise. /// internal static NestPipelineResult Run(INestingEngine engine, string engineName, NestJob job, IReadOnlyDictionary drawingsByPartId, IProgress progress, CancellationToken token, bool cutouts = true) { ArgumentNullException.ThrowIfNull(engine); ArgumentNullException.ThrowIfNull(job); NestJobValidator.Validate(job); var ordinary = RunOrdinary(engine, engineName, job, drawingsByPartId, progress, token, cutouts); return job.Options.UsesCommonLines ? WithCommonLines(engine, engineName, job, drawingsByPartId, ordinary, progress, token) : ordinary; } /// /// The common-line trials (see ), each solved after /// the ordinary solve and kept only when prefers it at the /// job's usage level; otherwise the ordinary result stands as it was. /// private static NestPipelineResult WithCommonLines(INestingEngine engine, string engineName, NestJob job, IReadOnlyDictionary drawingsByPartId, NestPipelineResult ordinary, IProgress progress, CancellationToken token) { var best = ordinary; var asked = new HashSet(StringComparer.Ordinal); foreach (var share in new[] { CommonLinePipelinePrepass.Share.All, CommonLinePipelinePrepass.Share.Half }) { token.ThrowIfCancellationRequested(); var prepass = CommonLinePipelinePrepass.Prepare(job, share, token); // Two shares that pair the same counts would ask the engine the same question. if (prepass == null || !asked.Add(string.Join("|", Remote.NestSolveTranscript.Fingerprint(prepass.EngineJob)))) continue; var trial = Evaluate(engine, engineName, job, prepass, drawingsByPartId, progress, token); if (CommonLineRanking.Prefers(job.Options.CommonLineUsage, trial, best)) best = trial; } return ReferenceEquals(best, ordinary) ? ordinary : Committed(best, progress, token); } private static NestPipelineResult RunOrdinary(INestingEngine engine, string engineName, NestJob job, IReadOnlyDictionary drawingsByPartId, IProgress progress, CancellationToken token, bool cutouts) { var prepass = cutouts ? CutoutPipelinePrepass.Prepare(job, token) : null; if (prepass == null) return Evaluate(engine, engineName, job, null, drawingsByPartId, progress, token); var trial = Evaluate(engine, engineName, job, prepass, drawingsByPartId, progress, token); var trialKeepable = trial.CanKeep && trial.IsValid; if (trialKeepable && trial.Status == NestJobStatus.Complete) return Committed(trial, progress, token); // Unplaced frames return their reserved inserts to unplaced demand, and an untrusted // composite is never bindable; the ordinary solve is the established baseline. var plain = Evaluate(engine, engineName, job, null, drawingsByPartId, progress, token); if (!trialKeepable) return plain.WithRefusedCutoutTrial(trial.Violations); if (plain.CanKeep && plain.IsValid && Placed(plain) > Placed(trial)) return plain; return Committed(trial, progress, token); } private static (NestJob Job, Dictionary Drawings) CreateJob( INestingEngine engine, NestPipelineRequest request, CancellationToken token ) { ArgumentNullException.ThrowIfNull(engine); return CreateJob(request, token); } /// The job the pipeline builds for (before any cutout /// bundling), and the caller drawing behind each part id. internal static (NestJob Job, Dictionary Drawings) CreateJob( NestPipelineRequest request, CancellationToken token ) { ArgumentNullException.ThrowIfNull(request); ArgumentNullException.ThrowIfNull(request.Items); ArgumentNullException.ThrowIfNull(request.Stock); token.ThrowIfCancellationRequested(); var drawingsByPartId = new Dictionary(StringComparer.Ordinal); var parts = new List(); for (var i = 0; i < request.Items.Count; i++) { var item = request.Items[i]; if (item == null || item.Quantity <= 0) continue; var partId = $"part-{i}"; parts.Add(DrawingJobMapper.FromItem(partId, item)); drawingsByPartId[partId] = item.Drawing; } var job = new NestJob(parts, request.Stock, request.Options); NestJobValidator.Validate(job); return (job, drawingsByPartId); } private static int Placed(NestPipelineResult result) => result.Raw.Plates.Sum(p => p.Placements.Count); // Trial progress hid the engine's proxy commit counts; report validated physical ones. private static NestPipelineResult Committed(NestPipelineResult result, IProgress progress, CancellationToken token) { var count = 0; for (var i = 0; i < result.Raw.Plates.Count; i++) { count += result.Raw.Plates[i].Placements.Count; progress?.Report(new NestJobProgress(NestJobStage.PlateCommitted, result.Raw.Plates[i].StockId, i, i + 1, count)); } token.ThrowIfCancellationRequested(); return result; } private static NestPipelineResult Evaluate( INestingEngine engine, string engineName, NestJob job, IPipelinePrepass prepass, IReadOnlyDictionary drawingsByPartId, IProgress progress, CancellationToken token ) { var engineJob = prepass?.EngineJob ?? job; IReadOnlyDictionary released = new Dictionary(); if (prepass != null) NestJobValidator.Validate(engineJob); var clock = Stopwatch.StartNew(); var engineProgress = progress == null ? null : new PlanProgress(prepass == null ? progress : new PreviewProgress(progress), engineJob, drawingsByPartId, token); var raw = engine.Solve(engineJob, engineProgress, token) ?? throw new InvalidOperationException($"Engine '{engineName}' returned no result."); var solveTime = clock.Elapsed; token.ThrowIfCancellationRequested(); // D8/C10: only the ordinary solve offers last-resort clamp removal; an incomplete // cutout trial is compared with that solve instead. No-op whenever nothing is blocked. if (prepass == null) { var recovered = ClampRemovalRecovery.TryRecover(job, raw, engine, token); if (recovered != null) { job = recovered.Job; engineJob = recovered.Job; raw = recovered.Result; } } token.ThrowIfCancellationRequested(); clock.Restart(); var names = drawingsByPartId.ToDictionary( kv => kv.Key, kv => kv.Value.Name ?? kv.Key, StringComparer.Ordinal ); var checkedNames = prepass == null ? names : engineJob.Parts.ToDictionary(p => p.Id, p => names.GetValueOrDefault(p.Id, p.Id), StringComparer.Ordinal); var violations = NestLayoutCheck.Violations(engineJob, raw, checkedNames, out var canKeep).ToList(); if (prepass != null) { // A compound may be physically invalid even when its envelope is legal. // Refuse every unverified trial, including with explicit invalid-result consent. var failure = prepass.ReconciliationFailure; if (violations.Count == 0 && prepass.TryExpand(job, raw, token, out var expanded, out failure)) { released = prepass.ReleasedInserts(raw); raw = expanded; violations.AddRange(NestLayoutCheck.Violations(job, raw, names, out var physicalKeep)); canKeep = physicalKeep && violations.Count == 0; } else { if (violations.Count == 0) violations.Add(failure); canKeep = false; } } var freshness = NestPipelineDrawingFreshness.Changes(job, drawingsByPartId); violations.AddRange(freshness); if (freshness.Count > 0) canKeep = false; var validationTime = clock.Elapsed; if (canKeep && violations.Count == 0) _ = NestJobCost.Evaluate(job, raw); // Invalid-but-representable output retains its physical review correspondence. var consolidate = violations.Count == 0; var plates = new List(); if (canKeep) foreach (var group in RepeatedPlateGrouping.Create(raw.Plates, consolidate, token)) { token.ThrowIfCancellationRequested(); var bound = NestResultBinder.Bind(group.Sheet, drawingsByPartId); plates.Add(new ProposedPlate(group.Sheet.PlateIndex, group.Sheet.Stock, bound) { Quantity = group.Quantity, CommonLines = NestResultBinder.BindCommonLines(group.Sheet, bound), }); } // Binding clones the caller's current Program; a concurrent edit during binding // must not return parts whose bytes differ from the already validated snapshot. if (canKeep) { var changes = NestPipelineDrawingFreshness.Changes(job, drawingsByPartId).ToList(); changes.AddRange(NestPipelineDrawingFreshness.BoundChanges(job, raw, plates, drawingsByPartId, consolidate, token)); if (changes.Count > 0) { violations.AddRange(changes); plates.Clear(); canKeep = false; } } token.ThrowIfCancellationRequested(); return new NestPipelineResult( engineName, job, raw, plates.AsReadOnly(), violations, canKeep, solveTime, validationTime, drawingsByPartId, NestUnplacedParts.Classify(job, raw, canKeep, drawingsByPartId, released) ); } }