@willcgage/module-schematic 0.46.0 → 0.48.0

package/dist/index.d.cts

@@ -412,6 +412,9 @@ interface ModuleFootprintInput {
      * When present it wins over the geometry-derived centre-line — the owner drew
      * the real shape (#2d-track, physical view only). */
     mainPath?: BenchworkPoint[] | null;
+    /** A balloon / return loop — the centre-line turns back on itself, so its far
+     * end is the THROAT, not an endplate; only endplate A's face is emitted (#loop). */
+    loop?: boolean;
 }
 interface OutlineFace {
     /** The endplate face's two corners + midpoint (the track point). */
@@ -1039,6 +1042,31 @@ interface EndplatePose {
     /** True when the pose was hand-entered, not derived (wye/loop/other). */
     manual?: boolean;
 }
+type ReturnLoopShape = "circle" | "teardrop" | "offset-teardrop" | "square";
+/** A computed return-loop: a mainline LEAD to the throat, a WYE that splits into
+ * two legs, and the LOOP track those legs form, closing back at the throat. Pure
+ * geometry, module-local inches, endplate A at the origin, lead heading +x. All
+ * shapes are built so the loop CLOSES exactly at the throat and the two wye legs
+ * diverge symmetrically about the lead — the piece the earlier eyeballed versions
+ * kept getting wrong (#loop). */
+interface ReturnLoopGeometry {
+    throat: BenchworkPoint;
+    /** The loop track, throat → around → throat (starts and ends at the throat). */
+    loop: BenchworkPoint[];
+    /** The two diverging wye legs at the throat (each throat → its tangent point). */
+    wyeLegs: [BenchworkPoint[], BenchworkPoint[]];
+    /** Half the angle between the two wye legs, degrees (0 = tangent/no wye). */
+    wyeHalfAngleDeg: number;
+    /** Benchwork fascia: outer boundary, and an inner boundary for a donut (empty
+     * when the board is solid). */
+    outlineOuter: BenchworkPoint[];
+    outlineInner: BenchworkPoint[];
+}
+declare function returnLoop(shape: ReturnLoopShape, opts: {
+    leadInches: number;
+    radius: number;
+    boardHalfWidth?: number;
+}): ReturnLoopGeometry;
 interface ModuleGeometryInput {
     lengthInches: number;
     geometryType?: string | null;
@@ -1138,4 +1166,4 @@ declare function poseOverridesFromDoc(doc: ModuleSchematicDoc): Record<string, {
     heading: number;
 }>;
 
-export { type BenchworkPoint, type BranchConnector, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type GeometryType, type IndustryLabelMode, type IndustrySpot, MAIN2_TRACK_ID, MAIN_TRACK_ID, type ModuleFeatures, type ModuleFootprint, type ModuleFootprintInput, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, type OutlineFace, type SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicIndustry, type SchematicSection, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SectionAdjacency, type SectionFootprint, type SectionRelativePos, type SignalFacing, type SignalSide, type TrackConfig, type TrackRole, type TurnoutKind, WHOLE_MODULE_SECTION_ID, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateLead, endplateTrackOffsetFor, endplateTrackOffsetInches, endplateWidthInches, fromSectionRelative, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, poseNeedsManual, poseOverridesFromDoc, remapPos, sampleBenchworkOutline, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, stateToDoc, toSectionRelative, trackMeetsEndplateIssues, trackPath };
+export { type BenchworkPoint, type BranchConnector, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type GeometryType, type IndustryLabelMode, type IndustrySpot, MAIN2_TRACK_ID, MAIN_TRACK_ID, type ModuleFeatures, type ModuleFootprint, type ModuleFootprintInput, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, type OutlineFace, type ReturnLoopGeometry, type ReturnLoopShape, type SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicIndustry, type SchematicSection, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SectionAdjacency, type SectionFootprint, type SectionRelativePos, type SignalFacing, type SignalSide, type TrackConfig, type TrackRole, type TurnoutKind, WHOLE_MODULE_SECTION_ID, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateLead, endplateTrackOffsetFor, endplateTrackOffsetInches, endplateWidthInches, fromSectionRelative, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, poseNeedsManual, poseOverridesFromDoc, remapPos, returnLoop, sampleBenchworkOutline, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, stateToDoc, toSectionRelative, trackMeetsEndplateIssues, trackPath };

package/dist/index.d.ts

@@ -412,6 +412,9 @@ interface ModuleFootprintInput {
      * When present it wins over the geometry-derived centre-line — the owner drew
      * the real shape (#2d-track, physical view only). */
     mainPath?: BenchworkPoint[] | null;
+    /** A balloon / return loop — the centre-line turns back on itself, so its far
+     * end is the THROAT, not an endplate; only endplate A's face is emitted (#loop). */
+    loop?: boolean;
 }
 interface OutlineFace {
     /** The endplate face's two corners + midpoint (the track point). */
@@ -1039,6 +1042,31 @@ interface EndplatePose {
     /** True when the pose was hand-entered, not derived (wye/loop/other). */
     manual?: boolean;
 }
+type ReturnLoopShape = "circle" | "teardrop" | "offset-teardrop" | "square";
+/** A computed return-loop: a mainline LEAD to the throat, a WYE that splits into
+ * two legs, and the LOOP track those legs form, closing back at the throat. Pure
+ * geometry, module-local inches, endplate A at the origin, lead heading +x. All
+ * shapes are built so the loop CLOSES exactly at the throat and the two wye legs
+ * diverge symmetrically about the lead — the piece the earlier eyeballed versions
+ * kept getting wrong (#loop). */
+interface ReturnLoopGeometry {
+    throat: BenchworkPoint;
+    /** The loop track, throat → around → throat (starts and ends at the throat). */
+    loop: BenchworkPoint[];
+    /** The two diverging wye legs at the throat (each throat → its tangent point). */
+    wyeLegs: [BenchworkPoint[], BenchworkPoint[]];
+    /** Half the angle between the two wye legs, degrees (0 = tangent/no wye). */
+    wyeHalfAngleDeg: number;
+    /** Benchwork fascia: outer boundary, and an inner boundary for a donut (empty
+     * when the board is solid). */
+    outlineOuter: BenchworkPoint[];
+    outlineInner: BenchworkPoint[];
+}
+declare function returnLoop(shape: ReturnLoopShape, opts: {
+    leadInches: number;
+    radius: number;
+    boardHalfWidth?: number;
+}): ReturnLoopGeometry;
 interface ModuleGeometryInput {
     lengthInches: number;
     geometryType?: string | null;
@@ -1138,4 +1166,4 @@ declare function poseOverridesFromDoc(doc: ModuleSchematicDoc): Record<string, {
     heading: number;
 }>;
 
-export { type BenchworkPoint, type BranchConnector, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type GeometryType, type IndustryLabelMode, type IndustrySpot, MAIN2_TRACK_ID, MAIN_TRACK_ID, type ModuleFeatures, type ModuleFootprint, type ModuleFootprintInput, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, type OutlineFace, type SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicIndustry, type SchematicSection, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SectionAdjacency, type SectionFootprint, type SectionRelativePos, type SignalFacing, type SignalSide, type TrackConfig, type TrackRole, type TurnoutKind, WHOLE_MODULE_SECTION_ID, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateLead, endplateTrackOffsetFor, endplateTrackOffsetInches, endplateWidthInches, fromSectionRelative, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, poseNeedsManual, poseOverridesFromDoc, remapPos, sampleBenchworkOutline, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, stateToDoc, toSectionRelative, trackMeetsEndplateIssues, trackPath };
+export { type BenchworkPoint, type BranchConnector, type DrawCrossing, type DrawCrossover, type DrawIndustry, type DrawSignal, type DrawTrack, type DrawTurnout, ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, type EditorBranch, type EditorControlPoint, type EditorCpSignal, type EditorCrossing, type EditorIndustry, type EditorState, type EditorTrack, type EditorTurnout, type EndplateBConfig, type EndplatePose, type EndplateTrackIssue, type EndplateWidthIssue, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, type GeometryType, type IndustryLabelMode, type IndustrySpot, MAIN2_TRACK_ID, MAIN_TRACK_ID, type ModuleFeatures, type ModuleFootprint, type ModuleFootprintInput, type ModuleGeometryInput, type ModuleSchematicDoc, type ModuleTrackRow, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, type OutlineFace, type ReturnLoopGeometry, type ReturnLoopShape, type SchematicBlock, type SchematicControlPoint, type SchematicCrossing, type SchematicEndplate, type SchematicEndplateTrack, type SchematicIndustry, type SchematicSection, type SchematicSignal, type SchematicTrack, type SchematicTurnout, type SectionAdjacency, type SectionFootprint, type SectionRelativePos, type SignalFacing, type SignalSide, type TrackConfig, type TrackRole, type TurnoutKind, WHOLE_MODULE_SECTION_ID, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateLead, endplateTrackOffsetFor, endplateTrackOffsetInches, endplateWidthInches, fromSectionRelative, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, poseNeedsManual, poseOverridesFromDoc, remapPos, returnLoop, sampleBenchworkOutline, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, stateToDoc, toSectionRelative, trackMeetsEndplateIssues, trackPath };

package/dist/index.js

@@ -472,7 +472,9 @@ function moduleFootprint(input) {
   return {
     centerline,
     band: benchworkBand(centerline, widthA, widthB, offA, offB),
-    endplateFaces: endplateFaceSegments(centerline, widthA, widthB, offA, offB),
+    // A loop's centre-line ends at the throat, not a far endplate — keep only
+    // endplate A's face (the far face would be a spurious plate at the throat).
+    endplateFaces: input.loop ? endplateFaceSegments(centerline, widthA, widthB, offA, offB).slice(0, 1) : endplateFaceSegments(centerline, widthA, widthB, offA, offB),
     outline: sectionOutlines.length || !authored ? null : sampleBenchworkOutline(authored),
     sectionOutlines
   };
@@ -1318,6 +1320,83 @@ function moduleFeatures(doc) {
     laneMax: Math.max(...allLanes)
   };
 }
+function returnLoop(shape, opts) {
+  const L = Math.max(1, opts.leadInches);
+  const R = Math.max(1, opts.radius);
+  const hw = Math.min(opts.boardHalfWidth ?? 6, R - 1);
+  const T = { x: L, y: 0 };
+  const r2 = (v) => Math.round(v * 100) / 100;
+  const rd = (pts) => pts.map((p) => ({ x: r2(p.x), y: r2(p.y) }));
+  const arc = (cx, cy, r, a0, a12, steps) => {
+    const out = [];
+    for (let i = 0; i <= steps; i++) out.push({ x: cx + r * Math.cos(a0 + (a12 - a0) * i / steps), y: cy + r * Math.sin(a0 + (a12 - a0) * i / steps) });
+    return out;
+  };
+  if (shape === "square") {
+    const s = 2 * R;
+    const loop2 = [
+      { x: L, y: 0 },
+      { x: L, y: R },
+      { x: L + s, y: R },
+      { x: L + s, y: -R },
+      { x: L, y: -R },
+      { x: L, y: 0 }
+    ];
+    return {
+      throat: T,
+      loop: rd(loop2),
+      wyeLegs: [rd([T, { x: L, y: R }]), rd([T, { x: L, y: -R }])],
+      wyeHalfAngleDeg: 90,
+      outlineOuter: rd([
+        { x: 0, y: hw },
+        { x: L + s + hw, y: hw },
+        { x: L + s + hw, y: -R - hw },
+        { x: 0, y: -R - hw }
+      ]),
+      outlineInner: rd([
+        { x: L + hw, y: R - hw },
+        { x: L + s - hw, y: R - hw },
+        { x: L + s - hw, y: -R + hw },
+        { x: L + hw, y: -R + hw }
+      ])
+    };
+  }
+  const D = shape === "circle" ? R * 1.15 : R * 1.6;
+  const offY = shape === "offset-teardrop" ? R * 0.7 : 0;
+  const C = { x: L + D, y: offY };
+  const dist = Math.hypot(C.x - T.x, C.y - T.y);
+  const ac = Math.acos(Math.min(1, R / dist));
+  const base = Math.atan2(T.y - C.y, T.x - C.x);
+  const a1 = base + ac;
+  const a2 = base - ac;
+  const P1 = { x: C.x + R * Math.cos(a1), y: C.y + R * Math.sin(a1) };
+  const P2 = { x: C.x + R * Math.cos(a2), y: C.y + R * Math.sin(a2) };
+  const loop = [T, P1, ...arc(C.x, C.y, R, a1, a2 + 2 * Math.PI, 64).slice(1), T];
+  const legDir = (P) => Math.atan2(P.y - T.y, P.x - T.x);
+  const half = Math.abs((legDir(P1) - legDir(P2) + Math.PI) % (2 * Math.PI) - Math.PI) / 2;
+  const ringOuter = (rr) => {
+    const xTop = C.x - Math.sqrt(Math.max(0, rr * rr - (hw - C.y) ** 2));
+    const xBot = C.x - Math.sqrt(Math.max(0, rr * rr - (-hw - C.y) ** 2));
+    const tTop = Math.atan2(hw - C.y, xTop - C.x);
+    const tBot = Math.atan2(-hw - C.y, xBot - C.x);
+    return [
+      { x: 0, y: hw },
+      { x: xTop, y: hw },
+      ...arc(C.x, C.y, rr, tTop, tBot - 2 * Math.PI, 48).slice(1, -1),
+      { x: xBot, y: -hw },
+      { x: 0, y: -hw }
+    ];
+  };
+  const Ri = R - hw;
+  return {
+    throat: T,
+    loop: rd(loop),
+    wyeLegs: [rd([T, P1]), rd([T, P2])],
+    wyeHalfAngleDeg: r2(half * 180 / Math.PI),
+    outlineOuter: rd(ringOuter(R + hw)),
+    outlineInner: Ri > 2 ? rd(arc(C.x, C.y, Ri, 0, 2 * Math.PI, 40)) : []
+  };
+}
 function geometryTurnDegrees(geometryType, geometryDegrees) {
   switch (geometryType) {
     case "corner_45":
@@ -1489,6 +1568,6 @@ function poseOverridesFromDoc(doc) {
   return out;
 }
 
-export { ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, MAIN2_TRACK_ID, MAIN_TRACK_ID, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, WHOLE_MODULE_SECTION_ID, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateLead, endplateTrackOffsetFor, endplateTrackOffsetInches, endplateWidthInches, fromSectionRelative, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, poseNeedsManual, poseOverridesFromDoc, remapPos, sampleBenchworkOutline, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, stateToDoc, toSectionRelative, trackMeetsEndplateIssues, trackPath };
+export { ENDPLATE_FASCIA_CLEAR_INCHES, ENDPLATE_LEAD_INCHES, FREEMO_ENDPLATE_TRACK_FASCIA_CLEARANCE_INCHES, FREEMO_ENDPLATE_WIDTH_MIN_INCHES, FREEMO_ENDPLATE_WIDTH_RECOMMENDED_INCHES, FREEMO_TRACK_SPACING_INCHES, MAIN2_TRACK_ID, MAIN_TRACK_ID, N_CAR_LENGTH_INCHES, N_SCALE_RATIO, WHOLE_MODULE_SECTION_ID, asModuleSchematic, benchworkBand, benchworkOutline, buildCrossover, buildPassingSiding, buildTransition, carCapacity, checkEndplateWidth, deriveEndplatePoses, divergeSideForHand, docToState, emptyEditorState, endplateFaceSegments, endplateLead, endplateTrackOffsetFor, endplateTrackOffsetInches, endplateWidthInches, fromSectionRelative, geometryTurnDegrees, inchesToScaleFeet, isLoopDoc, isTransitionTurnout, moduleCenterline, moduleFeatures, moduleFootprint, moduleLengthFromSections, moduleSections, nextId, poseNeedsManual, poseOverridesFromDoc, remapPos, returnLoop, sampleBenchworkOutline, samplePath, scaleFeetToInches, sectionAdjacency, sectionBand, sectionBreaksFromSections, sectionComponents, sectionFootprints, sectionNeighbours, sectionSpans, sectionSpansOrWhole, sectionedCenterline, sectionedEndPose, sliceCenterline, stateToDoc, toSectionRelative, trackMeetsEndplateIssues, trackPath };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map