@mlightcad/cad-simple-viewer 1.8.0-preview.2 → 1.8.0-preview.4

package/lib/smartBlock/AcApSmartBlockDetect.d.ts

@@ -0,0 +1,149 @@
+import type { AcDbDatabase, AcDbObjectId } from '@mlightcad/data-model';
+import { type AcApSmartBlockAttributeSpec, type AcApSmartBlockConvertResult } from './AcApSmartBlockConvert';
+import { AcApSmartBlockFeatureCache, type AcApSmartBlockMatch, type AcApSmartBlockSearchOptions } from './AcApSmartBlockSearch';
+/** Options of {@link acapDetectSmartBlocks} (`BDETECT`). */
+export interface AcApSmartBlockDetectOptions extends Pick<AcApSmartBlockSearchOptions, 'allowRotation' | 'allowMirror' | 'allowScale' | 'matchLayer' | 'textVariations'> {
+    /** Fewest instances (source included) a group needs. Default `3`. */
+    minInstances?: number;
+    /** Fewest non-text shapes per instance. Default `2`. */
+    minEntities?: number;
+    /**
+     * Smallest saving worth reporting: `instances × (entities − 1)`, the
+     * entities a conversion removes. Also prunes seeds whose estimate stays
+     * below it before the exact search runs. Default `10`.
+     */
+    minSavings?: number;
+    /** Most shapes per instance; growth stops there. Default `64`. */
+    maxEntities?: number;
+    /**
+     * Share of the seed occurrences that must agree on a shape before it
+     * joins the group. Default `0.8`.
+     */
+    agreement?: number;
+    /** Neighbors kept per shape (nearest first). Default `24`. */
+    neighborLimit?: number;
+    /**
+     * Most seed pair kinds tried, most frequent first. Default: all of them.
+     */
+    maxSeeds?: number;
+}
+/** One group of identical shapes found by {@link acapDetectSmartBlocks}. */
+export interface AcApSmartBlockCluster {
+    /**
+     * Entity ids of the representative instance. Pass them to
+     * `AcApSmartBlockSearch` to review and convert the group.
+     */
+    ids: AcDbObjectId[];
+    /** The other instances, verified by the Smart Blocks search. */
+    matches: AcApSmartBlockMatch[];
+    /** Number of instances, the representative included. */
+    instanceCount: number;
+    /** Entities per instance (texts included). */
+    entityCount: number;
+    /** Entities the conversion removes: `instances × (entities − 1)`. */
+    savings: number;
+}
+/** Options of {@link acapConvertSmartBlockCluster}. */
+export interface AcApSmartBlockClusterConvertOptions {
+    /** Name of the new block; must not exist yet. */
+    name: string;
+    /**
+     * Template point that becomes the insertion point. Default: the center of
+     * the representative, like AutoCAD.
+     */
+    basePoint?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Texts to store as attributes. Default: every text whose string differs
+     * between instances, tagged `TEXT1`, `TEXT2`, ...; pass `[]` for none.
+     */
+    attributes?: AcApSmartBlockAttributeSpec[];
+    /**
+     * Must equal the `matchLayer` the group was detected with, so the
+     * template lines up with the instances. Default `true`.
+     */
+    matchLayer?: boolean;
+}
+/**
+ * Converts a detected group into a new block: the representative and every
+ * instance become references of it. Call it inside one undo mark, like
+ * {@link acapConvertSmartBlock}. Instances must still be unchanged since
+ * detection.
+ *
+ * @param db - Drawing database the group was detected in.
+ * @param cluster - Group from {@link acapDetectSmartBlocks}.
+ * @param options - Block name, insertion point and attributes.
+ */
+export declare function acapConvertSmartBlockCluster(db: AcDbDatabase, cluster: AcApSmartBlockCluster, options: AcApSmartBlockClusterConvertOptions): AcApSmartBlockConvertResult;
+/**
+ * Finds groups of identical shapes anywhere in model space, without a
+ * selection: the heuristic counterpart of AutoCAD's Detect and Convert
+ * (`BDETECT`), which uses a cloud recognition model.
+ *
+ * Steps:
+ *
+ * 1. Every describable shape gets its neighbors, nearest first: shapes that
+ *    touch it (a characteristic point in its padded bounds) and shapes
+ *    whose bounds are closer than the smaller one's size.
+ * 2. Each neighbor pair gets a key that does not change under translation,
+ *    rotation and (optionally) mirroring: kinds, sizes, distance and the
+ *    second moments of both shapes in the pair's own frame. Keys that occur
+ *    at least `minInstances` times seed a group, most frequent first.
+ * 3. The seed occurrences grow together, round by round: a shape touching
+ *    the first occurrence joins when, in enough other occurrences, a shape
+ *    lands on it under that occurrence's transform. Walls and other shapes
+ *    that differ around each copy are left out.
+ * 4. Every round is rated by the exact matcher on just the shapes growth
+ *    collected; the best round is then verified on the whole drawing by
+ *    the Smart Blocks search ({@link acapFindSmartBlockMatches}).
+ * 5. A seed pair may play different roles in one symbol (an arc at a
+ *    corner and at an end), which stops growth early. The verified copies
+ *    are consistent, so the group grows again from them, absorbing earlier
+ *    groups that turn out to be parts of it when the whole saves more.
+ * 6. Texts inside the group join it when most copies have one there; with
+ *    text variations they become attributes on conversion.
+ * 7. The copies' entities are claimed so groups never share entities.
+ *    Groups saving fewer than `minSavings` entities are dropped.
+ *
+ * Every group can be reviewed and converted with `AcApSmartBlockSearch`
+ * from its {@link AcApSmartBlockCluster.ids}. That search may find more
+ * copies than reported here: copies used by another group are not counted.
+ *
+ * Groups are returned largest saving first.
+ *
+ * @param db - Drawing database.
+ * @param options - Thresholds and allowed transforms.
+ * @param cache - Feature cache shared with later searches.
+ */
+export declare function acapDetectSmartBlocks(db: AcDbDatabase, options?: AcApSmartBlockDetectOptions, cache?: AcApSmartBlockFeatureCache): AcApSmartBlockCluster[];
+/** Progress of {@link acapDetectSmartBlocksAsync}. */
+export interface AcApSmartBlockDetectProgress {
+    /** Share of the work done, `0` to `1`. */
+    fraction: number;
+    /** Groups found so far. */
+    groups: number;
+}
+/** Progress reporting and cancellation of {@link acapDetectSmartBlocksAsync}. */
+export interface AcApSmartBlockDetectControl {
+    /** Called between slices of work. */
+    onProgress?: (progress: AcApSmartBlockDetectProgress) => void;
+    /** Aborts the detection; the promise then rejects with the signal's reason. */
+    signal?: AbortSignal;
+    /** Longest stretch of work before yielding to the event loop. Default 30 ms. */
+    sliceMs?: number;
+}
+/**
+ * {@link acapDetectSmartBlocks} in slices, yielding to the event loop
+ * between them so a UI stays responsive, with progress and cancellation.
+ * Single steps (one exact search) can still take a moment in large
+ * drawings.
+ *
+ * @param db - Drawing database; do not edit it until the promise settles.
+ * @param options - Thresholds and allowed transforms.
+ * @param control - Progress callback, abort signal and slice length.
+ * @param cache - Feature cache shared with later searches.
+ */
+export declare function acapDetectSmartBlocksAsync(db: AcDbDatabase, options?: AcApSmartBlockDetectOptions, control?: AcApSmartBlockDetectControl, cache?: AcApSmartBlockFeatureCache): Promise<AcApSmartBlockCluster[]>;
+//# sourceMappingURL=AcApSmartBlockDetect.d.ts.map

package/lib/smartBlock/AcApSmartBlockDetect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcApSmartBlockDetect.d.ts","sourceRoot":"","sources":["../../src/smartBlock/AcApSmartBlockDetect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EAEZ,YAAY,EACb,MAAM,uBAAuB,CAAA;AAG9B,OAAO,EAGL,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EACjC,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAKL,0BAA0B,EAC1B,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAGjC,MAAM,wBAAwB,CAAA;AAS/B,4DAA4D;AAC5D,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CACvD,2BAA2B,EACzB,eAAe,GACf,aAAa,GACb,YAAY,GACZ,YAAY,GACZ,gBAAgB,CACnB;IACC,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,GAAG,EAAE,YAAY,EAAE,CAAA;IACnB,gEAAgE;IAChE,OAAO,EAAE,mBAAmB,EAAE,CAAA;IAC9B,wDAAwD;IACxD,aAAa,EAAE,MAAM,CAAA;IACrB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAA;IACnB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,uDAAuD;AACvD,MAAM,WAAW,mCAAmC;IAClD,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,SAAS,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,2BAA2B,EAAE,CAAA;IAC1C;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,mCAAmC,GAC3C,2BAA2B,CAqB7B;AAiDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,YAAY,EAChB,OAAO,GAAE,2BAAgC,EACzC,KAAK,GAAE,0BAA6D,GACnE,qBAAqB,EAAE,CAMzB;AAED,sDAAsD;AACtD,MAAM,WAAW,4BAA4B;IAC3C,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAA;CACf;AAED,iFAAiF;AACjF,MAAM,WAAW,2BAA2B;IAC1C,qCAAqC;IACrC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,4BAA4B,KAAK,IAAI,CAAA;IAC7D,+EAA+E;IAC/E,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,EAAE,EAAE,YAAY,EAChB,OAAO,GAAE,2BAAgC,EACzC,OAAO,GAAE,2BAAgC,EACzC,KAAK,GAAE,0BAA6D,GACnE,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAiBlC"}