@ifc-lite/bcf 1.18.2 → 2.0.1

package/dist/reader-components.js

@@ -0,0 +1,202 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+import { extractElement, unescapeXml } from './xml-text.js';
+/**
+ * Every `<Component>` element in an XML fragment.
+ *
+ * The two branches are spelled out rather than factored behind a common
+ * `<Component[^>]*` prefix as
+ * `<Component[^>]*(?:\/>|>[\s\S]*?<\/Component>)`, and that is the whole
+ * point: `[^>]*` is greedy and eats the `/` of a self-closing tag, so the
+ * `\/>` alternative can never fire. A uniform list still parsed, because the
+ * engine backtracks and gives the `/` back when no later `</Component>`
+ * exists. A MIXED list did not: `<Component .../><Component ...>...</Component>`
+ * matched as ONE element spanning both, and the first component silently
+ * inherited the second's `authoringToolId` and `originatingSystem`.
+ *
+ * That is why every fixture passed. Uniform lists are the only shape the suite
+ * had, and they are the one shape the defect cannot reach.
+ */
+const COMPONENT_ELEMENT = /<Component[^>]*?\/>|<Component[^>]*>[\s\S]*?<\/Component>/g;
+/** Parse each `<Component>` in `xml`, dropping any that does not parse. */
+function parseComponentElements(xml) {
+    const components = [];
+    for (const match of xml.matchAll(COMPONENT_ELEMENT)) {
+        const component = parseComponent(match[0]);
+        if (component)
+            components.push(component);
+    }
+    return components;
+}
+/**
+ * Parse components (selection/visibility/coloring)
+ */
+export function parseComponents(content) {
+    const componentsMatch = content.match(/<Components>([\s\S]*?)<\/Components>/);
+    if (!componentsMatch)
+        return undefined;
+    const componentsContent = componentsMatch[1];
+    // Parse selection
+    const selection = parseComponentList(componentsContent, 'Selection');
+    // Parse visibility
+    let visibility = parseVisibility(componentsContent);
+    // Parse coloring
+    const coloring = parseColoring(componentsContent);
+    // Nothing read `ViewSetupHints` back, so every hint was lost on read —
+    // including out of our own archives. It was invisible because no writer
+    // fixture set the hints, so the round trip compared `undefined` to
+    // `undefined`.
+    //
+    // Searched across the whole `Components` body on purpose, because the two
+    // schema versions disagree on placement: 2.1 puts the element on
+    // `Components`, 3.0 nests it inside `Visibility`, and `writer.ts` emits
+    // whichever the requested version calls for. Anchoring to either one would
+    // read half the files we produce.
+    const viewSetupHints = parseViewSetupHints(componentsContent);
+    if (viewSetupHints) {
+        // Visibility is required by the schema, but tolerate a file that omits it:
+        // DefaultVisibility's schema default is true.
+        visibility = { ...(visibility ?? { defaultVisibility: true }), viewSetupHints };
+    }
+    if (!selection && !visibility && !coloring) {
+        return undefined;
+    }
+    return {
+        selection: selection?.length ? selection : undefined,
+        visibility,
+        coloring: coloring?.length ? coloring : undefined,
+    };
+}
+/**
+ * Parse a list of components
+ */
+function parseComponentList(content, elementName) {
+    const match = content.match(new RegExp(`<${elementName}>([\\s\\S]*?)<\\/${elementName}>`));
+    if (!match)
+        return undefined;
+    const components = parseComponentElements(match[1]);
+    return components.length > 0 ? components : undefined;
+}
+/**
+ * Parse a single component
+ */
+function parseComponent(content) {
+    const ifcGuidMatch = content.match(/IfcGuid="([^"]+)"/);
+    /** An attribute value, decoded the same way `extractElement` decodes an
+     *  element's text, so `AuthoringToolId="A &amp; B"` and the element spelling
+     *  of the same field yield the same string. Deliberately not
+     *  `reader.ts::extractAttr`, which is contracted to take an already-captured
+     *  attribute string and does not decode entities. Without this the two spellings of the SAME field
+     *  disagreed: `AuthoringToolId="A &amp; B"` came back as the literal
+     *  `A &amp; B` while `<AuthoringToolId>A &amp; B</AuthoringToolId>` came back
+     *  as `A & B`. Which one a file uses is not supposed to change its value. */
+    // Only the OPENING TAG. `content` is the whole element, so an unscoped
+    // search reads a CHILD's attribute as the component's own:
+    // `<Component IfcGuid="G"><Child OriginatingSystem="x"/></Component>` used to
+    // report `x`. `\b` for the same reason `reader.ts::extractAttr` has it, or
+    // `XAuthoringToolId="sneaky"` satisfies a search for `AuthoringToolId`.
+    const openingTag = content.slice(0, content.indexOf('>') + 1);
+    const attribute = (name) => {
+        const raw = openingTag.match(new RegExp(`\\b${name}="([^"]*)"`))?.[1];
+        return raw ? unescapeXml(raw) : undefined;
+    };
+    // Per BCF 2.1 §"Component" (unchanged in 3.0) only `IfcGuid` is an
+    // attribute; `OriginatingSystem` and `AuthoringToolId` are child
+    // ELEMENTS — which is exactly what writeComponent() emits. Reading them
+    // as attributes matched nothing, so both fields were dropped from every
+    // archive, ifc-lite's own included. The attribute spellings are still
+    // accepted as a fallback so files from tools that emit the non-spec form
+    // keep working; the element form wins when both are present.
+    // `|| undefined`, not `??`: an EMPTY element (`<AuthoringToolId></...>`) has
+    // to read the same as an empty attribute and as an absent one. Without it
+    // the element form returned `''`, which survived the identity guard below
+    // with no identity at all, and `writeComponent` then wrote it back as a bare
+    // `<Component/>` that the reader discards. Three spellings of "nothing"
+    // disagreeing is the same defect this file exists to fix.
+    const authoringToolId = (extractElement(content, 'AuthoringToolId') || undefined) ?? attribute('AuthoringToolId');
+    const originatingSystem = (extractElement(content, 'OriginatingSystem') || undefined) ?? attribute('OriginatingSystem');
+    // A component needs some identity to be meaningful. `IfcGuid` is optional
+    // in the schema, so `AuthoringToolId` alone is a valid identification —
+    // and used to be discarded here because it was never found.
+    if (!ifcGuidMatch && authoringToolId === undefined) {
+        return undefined;
+    }
+    return {
+        ifcGuid: ifcGuidMatch?.[1] === undefined ? undefined : unescapeXml(ifcGuidMatch[1]),
+        authoringToolId,
+        originatingSystem,
+    };
+}
+/**
+ * Parse visibility settings
+ */
+function parseVisibility(content) {
+    // Both branches, for the same reason as `COMPONENT_ELEMENT`: `<Exceptions>`
+    // and `<ViewSetupHints>` are optional, so `<Visibility DefaultVisibility=
+    // "false"/>` is schema-legal. Matching only the paired form made the whole
+    // `<Components>` block return undefined for such a file, dropping the
+    // selection and colouring with it. ifc-lite's own writer always emits the
+    // paired form, which is why no fixture reached this.
+    const visibilityMatch = content.match(/<Visibility[^>]*?\/>|<Visibility[^>]*>[\s\S]*?<\/Visibility>/);
+    if (!visibilityMatch)
+        return undefined;
+    // Read from the `<Visibility>` element, NOT from the enclosing `<Components>`
+    // string: a `DefaultVisibility` attribute on any earlier element (a
+    // `<Selection>` component, say) won the match and inverted the answer, so a
+    // file saying show-all hid everything.
+    const defaultVisMatch = visibilityMatch[0].match(/DefaultVisibility="([^"]+)"/);
+    const defaultVisibility = defaultVisMatch?.[1] !== 'false';
+    const exceptions = parseComponentList(visibilityMatch[0], 'Exceptions');
+    return {
+        defaultVisibility,
+        exceptions,
+    };
+}
+/**
+ * Parse coloring settings
+ */
+function parseColoring(content) {
+    const coloringMatch = content.match(/<Coloring>([\s\S]*?)<\/Coloring>/);
+    if (!coloringMatch)
+        return undefined;
+    const colorings = [];
+    const colorMatches = coloringMatch[1].matchAll(/<Color\s+Color="([^"]+)"[^>]*>([\s\S]*?)<\/Color>/g);
+    for (const match of colorMatches) {
+        const color = match[1];
+        const components = parseComponentElements(match[2]);
+        if (components.length > 0) {
+            colorings.push({ color, components });
+        }
+    }
+    return colorings.length > 0 ? colorings : undefined;
+}
+/**
+ * Parse the `<ViewSetupHints>` element that sits directly under `<Components>`.
+ *
+ * All three attributes are optional xs:boolean; an absent one stays `undefined`
+ * rather than collapsing to `false`, because "the author did not say" and "the
+ * author said no" mean different things to a viewer applying the hints.
+ */
+function parseViewSetupHints(content) {
+    const match = content.match(/<ViewSetupHints\b([^>]*)>/);
+    if (!match)
+        return undefined;
+    const attrs = match[1];
+    const flag = (name) => {
+        const raw = attrs.match(new RegExp(`\\b${name}="([^"]*)"`))?.[1];
+        if (raw === undefined)
+            return undefined;
+        return raw === 'true' || raw === '1';
+    };
+    const spacesVisible = flag('SpacesVisible');
+    const spaceBoundariesVisible = flag('SpaceBoundariesVisible');
+    const openingsVisible = flag('OpeningsVisible');
+    if (spacesVisible === undefined
+        && spaceBoundariesVisible === undefined
+        && openingsVisible === undefined) {
+        return undefined;
+    }
+    return { spacesVisible, spaceBoundariesVisible, openingsVisible };
+}
+//# sourceMappingURL=reader-components.js.map

package/dist/reader-components.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader-components.js","sourceRoot":"","sources":["../src/reader-components.ts"],"names":[],"mappings":"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"}

package/dist/reader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../src/reader.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,UAAU,EAoBX,MAAM,YAAY,CAAC;AAyIpB;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,WAAW,GAAG,UAAU,EAC5C,MAAM,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GACpF,OAAO,CAAC,UAAU,CAAC,CA4CrB"}
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../src/reader.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,UAAU,EAgBX,MAAM,YAAY,CAAC;AAyIpB;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC3B,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,WAAW,GAAG,UAAU,EAC5C,MAAM,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GACpF,OAAO,CAAC,UAAU,CAAC,CA4CrB"}

package/dist/reader.js

@@ -7,6 +7,8 @@
  * Parses .bcfzip files into BCFProject structure
  */
 import JSZip from 'jszip';
+import { parseComponents } from './reader-components.js';
+import { extractElement, unescapeXml } from './xml-text.js';
 import { parseFiniteFloat } from './numeric.js';
 /**
  * Resource caps guarding against a malicious (zip-bomb) .bcfzip: a tiny
@@ -177,10 +179,14 @@ async function readProjectFile(zip, budget) {
     }
     const content = await readEntryCapped(projectFile, 'string', budget);
     const projectIdMatch = content.match(/ProjectId="([^"]+)"/);
-    const nameMatch = content.match(/<Name>([^<]+)<\/Name>/);
+    // extractElement, not a raw regex: writeProjectFile escapes the name with
+    // escapeXml, so a raw match hands back the literal entities (`A &amp; B`) and
+    // the next export escapes them again. Every other element in this reader goes
+    // through extractElement precisely so the escape has an inverse.
+    const name = extractElement(content, 'Name');
     return {
         projectId: projectIdMatch?.[1],
-        name: nameMatch?.[1],
+        name,
     };
 }
 /**
@@ -348,47 +354,31 @@ function parseHeaderFiles(markupContent) {
 function extractAttr(attrsString, attrName) {
     return attrsString.match(new RegExp(`\\b${attrName}="([^"]*)"`))?.[1];
 }
-/**
- * Extract a simple element value from XML
- *
- * Values are unescaped so writer.ts's escapeXml() round-trips correctly
- * (see escapeXml/unescapeXml regression: & < > " ' in titles/descriptions/
- * comments must come back exactly as written, not as literal entities).
- */
-function extractElement(content, elementName) {
-    const match = content.match(new RegExp(`<${elementName}>([^<]*)<\\/${elementName}>`));
-    return match?.[1] !== undefined ? unescapeXml(match[1]) : undefined;
-}
-/**
- * Unescape XML entities produced by writer.ts's escapeXml()
- *
- * &amp; must be decoded last so a literal "&lt;" written as "&amp;lt;"
- * doesn't get corrupted into "<" by an earlier pass.
- */
-function unescapeXml(str) {
-    return str
-        .replace(/&lt;/g, '<')
-        .replace(/&gt;/g, '>')
-        .replace(/&quot;/g, '"')
-        .replace(/&apos;/g, "'")
-        .replace(/&amp;/g, '&');
-}
 /**
  * Extract BIM snippet from topic content
  */
 function extractBimSnippet(content) {
-    const match = content.match(/<BimSnippet\s+SnippetType="([^"]+)"[^>]*>([\s\S]*?)<\/BimSnippet>/);
+    // Attributes are captured generically and pulled out with extractAttr rather
+    // than anchoring SnippetType to first position: our own writer always emits
+    // it first, so an anchored regex round-trips our files and silently drops the
+    // entire snippet from a foreign tool's file that orders the two attributes
+    // the other way (see extractAttr's note on attribute order).
+    const match = content.match(/<BimSnippet\b([^>]*)>([\s\S]*?)<\/BimSnippet>/);
     if (!match)
         return undefined;
+    const snippetType = extractAttr(match[1], 'SnippetType');
+    if (!snippetType)
+        return undefined;
     // BCF 2.1 spells this `isExternal`, 3.0 `IsExternal` (same rename as the
     // Header `<File>` attribute in reader.ts's parseHeaderFiles); accept either
-    // casing so a spec-correct 3.0 file's flag isn't silently read as false.
-    const isExternalMatch = match[0].match(/\b[Ii]sExternal="([^"]+)"/);
+    // casing so a spec-correct 3.0 file's flag isn't silently read as false, and
+    // the xs:boolean `1`/`0` forms alongside `true`/`false`.
+    const isExternalRaw = match[1].match(/\b[Ii]sExternal="([^"]*)"/)?.[1];
     const reference = extractElement(match[2], 'Reference');
     const referenceSchema = extractElement(match[2], 'ReferenceSchema');
     return {
-        snippetType: match[1],
-        isExternal: isExternalMatch?.[1] === 'true',
+        snippetType,
+        isExternal: isExternalRaw === 'true' || isExternalRaw === '1',
         reference: reference || '',
         referenceSchema,
     };
@@ -522,6 +512,33 @@ async function parseViewpoints(zip, topicFolder, markupContent, budget) {
             snapshotFile: snapshotFileMatch?.[1],
         });
     }
+    // BCF 3.0 nests viewpoint entries inside <Topic>, wrapped in a plural
+    // <Viewpoints> container that (unlike 2.1's) carries no Guid itself; each
+    // entry is a singular <ViewPoint Guid="..."> -- capital P, distinct from
+    // the lowercase-p <Viewpoint Guid="..."/> a Comment uses to reference a
+    // viewpoint -- per buildingSMART/BCF-XML markup.xsd (release_3_0, Topic's
+    // Viewpoints element wraps `ViewPoint` entries) and confirmed against the
+    // buildingSMART/BCF-XML Test Cases/v3.0/Visualization/Perspective camera
+    // fixture, whose markup.bcf reads
+    // `<Viewpoints><ViewPoint Guid="f99eb1ed-...">`. The plural-with-Guid regex
+    // above can never match this shape (the wrapper has no Guid attribute), so
+    // without this pass every 3.0 file's markup-declared snapshot filename was
+    // silently dropped and resolution fell through to guessing our own
+    // Snapshot_<guid> naming convention -- which a third-party 3.0 file has no
+    // reason to follow.
+    const viewPointElementRegex = /<ViewPoint\b([^>]*)>([\s\S]*?)<\/ViewPoint>/g;
+    for (const match of markupContent.matchAll(viewPointElementRegex)) {
+        const guid = extractAttr(match[1], 'Guid');
+        if (!guid || viewpointInfoMap.has(guid))
+            continue;
+        const content = match[2];
+        const viewpointFileMatch = content.match(/<Viewpoint>([^<]+)<\/Viewpoint>/);
+        const snapshotFileMatch = content.match(/<Snapshot>([^<]+)<\/Snapshot>/);
+        viewpointInfoMap.set(guid, {
+            viewpointFile: viewpointFileMatch?.[1],
+            snapshotFile: snapshotFileMatch?.[1],
+        });
+    }
     // Also match self-closing viewpoint references
     const simpleViewpointRefs = markupContent.matchAll(/<Viewpoints\b([^>]*)\/>/g);
     for (const match of simpleViewpointRefs) {
@@ -677,8 +694,33 @@ function parsePerspectiveCamera(content) {
         cameraDirection: direction,
         cameraUpVector: upVector,
         fieldOfView: fov,
+        ...parseAspectRatio(cameraContent),
     };
 }
+/**
+ * Parse the optional `<AspectRatio>` of either camera type.
+ *
+ * BCF 3.0's visinfo.xsd makes `AspectRatio` (a `PositiveDouble`) a REQUIRED
+ * child of both camera types; BCF 2.1 has no such element. It is read here for
+ * both, since the element's presence — not the archive's declared version — is
+ * what says whether there is a value to keep.
+ *
+ * Reading it matters beyond fidelity: the writer refuses to emit a 3.0 camera
+ * without one, so a 3.0 archive from another tool could otherwise be read and
+ * then not written back. Returned as a spread-able partial so an absent or
+ * unusable value leaves the property off entirely rather than setting it to
+ * `undefined`, and a non-positive value is dropped rather than carried into
+ * output the schema would reject.
+ */
+function parseAspectRatio(cameraContent) {
+    const raw = extractElement(cameraContent, 'AspectRatio');
+    if (!raw)
+        return {};
+    const value = parseFiniteFloat(raw);
+    if (value === undefined || !(value > 0))
+        return {};
+    return { aspectRatio: value };
+}
 /**
  * Parse orthogonal camera from viewpoint content
  */
@@ -705,6 +747,7 @@ function parseOrthogonalCamera(content) {
         cameraDirection: direction,
         cameraUpVector: upVector,
         viewToWorldScale: scale,
+        ...parseAspectRatio(cameraContent),
     };
 }
 /**
@@ -743,102 +786,6 @@ function parsePoint(content, elementName) {
 function parseDirection(content, elementName) {
     return parsePoint(content, elementName);
 }
-/**
- * Parse components (selection/visibility/coloring)
- */
-function parseComponents(content) {
-    const componentsMatch = content.match(/<Components>([\s\S]*?)<\/Components>/);
-    if (!componentsMatch)
-        return undefined;
-    const componentsContent = componentsMatch[1];
-    // Parse selection
-    const selection = parseComponentList(componentsContent, 'Selection');
-    // Parse visibility
-    const visibility = parseVisibility(componentsContent);
-    // Parse coloring
-    const coloring = parseColoring(componentsContent);
-    if (!selection && !visibility && !coloring) {
-        return undefined;
-    }
-    return {
-        selection: selection?.length ? selection : undefined,
-        visibility,
-        coloring: coloring?.length ? coloring : undefined,
-    };
-}
-/**
- * Parse a list of components
- */
-function parseComponentList(content, elementName) {
-    const match = content.match(new RegExp(`<${elementName}>([\\s\\S]*?)<\\/${elementName}>`));
-    if (!match)
-        return undefined;
-    const components = [];
-    const componentMatches = match[1].matchAll(/<Component[^>]*(?:\/>|>[\s\S]*?<\/Component>)/g);
-    for (const compMatch of componentMatches) {
-        const component = parseComponent(compMatch[0]);
-        if (component) {
-            components.push(component);
-        }
-    }
-    return components.length > 0 ? components : undefined;
-}
-/**
- * Parse a single component
- */
-function parseComponent(content) {
-    const ifcGuidMatch = content.match(/IfcGuid="([^"]+)"/);
-    const authoringToolIdMatch = content.match(/AuthoringToolId="([^"]+)"/);
-    const originatingSystemMatch = content.match(/OriginatingSystem="([^"]+)"/);
-    if (!ifcGuidMatch && !authoringToolIdMatch) {
-        return undefined;
-    }
-    return {
-        ifcGuid: ifcGuidMatch?.[1],
-        authoringToolId: authoringToolIdMatch?.[1],
-        originatingSystem: originatingSystemMatch?.[1],
-    };
-}
-/**
- * Parse visibility settings
- */
-function parseVisibility(content) {
-    const visibilityMatch = content.match(/<Visibility[^>]*>([\s\S]*?)<\/Visibility>/);
-    if (!visibilityMatch)
-        return undefined;
-    const defaultVisMatch = content.match(/DefaultVisibility="([^"]+)"/);
-    const defaultVisibility = defaultVisMatch?.[1] !== 'false';
-    const exceptions = parseComponentList(visibilityMatch[1], 'Exceptions');
-    return {
-        defaultVisibility,
-        exceptions,
-    };
-}
-/**
- * Parse coloring settings
- */
-function parseColoring(content) {
-    const coloringMatch = content.match(/<Coloring>([\s\S]*?)<\/Coloring>/);
-    if (!coloringMatch)
-        return undefined;
-    const colorings = [];
-    const colorMatches = coloringMatch[1].matchAll(/<Color\s+Color="([^"]+)"[^>]*>([\s\S]*?)<\/Color>/g);
-    for (const match of colorMatches) {
-        const color = match[1];
-        const components = [];
-        const componentMatches = match[2].matchAll(/<Component[^>]*(?:\/>|>[\s\S]*?<\/Component>)/g);
-        for (const compMatch of componentMatches) {
-            const component = parseComponent(compMatch[0]);
-            if (component) {
-                components.push(component);
-            }
-        }
-        if (components.length > 0) {
-            colorings.push({ color, components });
-        }
-    }
-    return colorings.length > 0 ? colorings : undefined;
-}
 /**
  * Parse lines
  */
@@ -877,20 +824,30 @@ function parseClippingPlanes(content) {
 }
 /**
  * Parse bitmaps
+ *
+ * The two BCF versions diverge in shape (see writer.ts's writeBitmap/
+ * writeViewpointFiles for the write side of this):
+ * - BCF 3.0: entries sit inside a `<Bitmaps>` wrapper, and the per-entry
+ *   format element is named `<Format>`. No tag inside an entry shares the
+ *   entry's own name, so a plain non-greedy `<Bitmap>...</Bitmap>` match
+ *   is unambiguous.
+ * - BCF 2.1: entries sit DIRECTLY under `<VisualizationInfo>` (no wrapper),
+ *   and the format element is confusingly also named `<Bitmap>`, nested one
+ *   level inside the entry (`<Bitmap><Bitmap>PNG</Bitmap><Reference>...`).
+ *   A naive non-greedy `<Bitmap>...</Bitmap>` match on that shape terminates
+ *   at the FIRST `</Bitmap>` it sees -- the inner format tag's closing tag,
+ *   not the entry's -- and silently drops the rest of the entry. It must be
+ *   matched with an explicit two-level pattern instead.
  */
 function parseBitmaps(content) {
     const bitmaps = [];
     const bitmapsMatch = content.match(/<Bitmaps>([\s\S]*?)<\/Bitmaps>/);
-    if (!bitmapsMatch)
-        return bitmaps;
-    const bitmapMatches = bitmapsMatch[1].matchAll(/<Bitmap>([\s\S]*?)<\/Bitmap>/g);
-    for (const match of bitmapMatches) {
-        const format = extractElement(match[1], 'Format') || extractElement(match[1], 'Bitmap');
-        const reference = extractElement(match[1], 'Reference');
-        const location = parsePoint(match[1], 'Location');
-        const normal = parseDirection(match[1], 'Normal');
-        const up = parseDirection(match[1], 'Up');
-        const height = extractElement(match[1], 'Height');
+    const pushBitmap = (format, body) => {
+        const reference = extractElement(body, 'Reference');
+        const location = parsePoint(body, 'Location');
+        const normal = parseDirection(body, 'Normal');
+        const up = parseDirection(body, 'Up');
+        const height = extractElement(body, 'Height');
         if (format && reference && location && normal && up && height) {
             bitmaps.push({
                 format: format.toUpperCase() === 'JPG' ? 'JPG' : 'PNG',
@@ -901,6 +858,19 @@ function parseBitmaps(content) {
                 height: parseFloat(height),
             });
         }
+    };
+    if (bitmapsMatch) {
+        // BCF 3.0 shape: <Bitmaps><Bitmap><Format>...</Format>...</Bitmap>...</Bitmaps>
+        for (const match of bitmapsMatch[1].matchAll(/<Bitmap>([\s\S]*?)<\/Bitmap>/g)) {
+            pushBitmap(extractElement(match[1], 'Format'), match[1]);
+        }
+    }
+    else {
+        // BCF 2.1 shape: <Bitmap><Bitmap>PNG</Bitmap>...</Bitmap>, unwrapped,
+        // directly under VisualizationInfo.
+        for (const match of content.matchAll(/<Bitmap>\s*<Bitmap>([\s\S]*?)<\/Bitmap>([\s\S]*?)<\/Bitmap>/g)) {
+            pushBitmap(match[1], match[2]);
+        }
     }
     return bitmaps;
 }