@jetta/blocks-allocator 0.0.0-stage → 0.1.0-0

package/src/Allocation_Optimization/tie_ratio/loose_on_block/build_placement_on_generic_supporter.js

@@ -0,0 +1,64 @@
+const resolve_placement_y_at_slot = require('./resolve_placement_y_at_slot')
+const placement_coords_fit_inside_container = require('./placement_coords_fit_inside_container')
+const { register_pending_footprint } = require('./loose_on_block_slot_state')
+
+/**
+ * @param {object[]} candidates
+ * @param {object} supporter
+ * @param {object|undefined} slot_state
+ * @param {object} placement_options
+ * @param {object|undefined} container
+ * @returns {{ x: number, y: number, z: number }|undefined}
+ */
+function build_placement_on_generic_supporter(
+    candidates,
+    supporter,
+    slot_state,
+    placement_options,
+    container
+)
+{
+    const slot = {
+        x: supporter.get_x(),
+        z: supporter.get_z(),
+        supporter_item: supporter,
+        index: 0
+    }
+    const placement_y = resolve_placement_y_at_slot(
+        candidates,
+        slot,
+        slot_state
+    )
+    const placement = {
+        x: supporter.get_x(),
+        y: placement_y,
+        z: supporter.get_z()
+    }
+    if (!placement_coords_fit_inside_container(
+        container,
+        placement.x,
+        placement.y,
+        placement.z,
+        placement_options.item_width,
+        placement_options.item_height,
+        placement_options.item_length
+    ))
+    {
+        return undefined
+    }
+    if (slot_state !== undefined)
+    {
+        register_pending_footprint(
+            slot_state,
+            placement.y,
+            placement.x,
+            placement.z,
+            placement_options.item_width,
+            placement_options.item_length,
+            placement_options.item_height
+        )
+    }
+    return placement
+}
+
+module.exports = build_placement_on_generic_supporter

package/src/Allocation_Optimization/tie_ratio/loose_on_block/build_slot_grid_from_cluster.js

@@ -0,0 +1,66 @@
+const math = require('@jetta/number-compare')
+const block_local_origin = require('./block_local_origin')
+
+/**
+ * @typedef {object} Supporter_Slot
+ * @property {number} index
+ * @property {number} offset_x
+ * @property {number} offset_z
+ * @property {number} x
+ * @property {number} z
+ * @property {object} supporter_item
+ */
+
+/**
+ * Builds a stable slot grid from supporter cluster item positions.
+ * @param {object[]} cluster_items
+ * @returns {Supporter_Slot[]}
+ */
+function build_slot_grid_from_cluster(cluster_items)
+{
+    const origin = block_local_origin(cluster_items)
+    const slots = cluster_items.map((supporter_item, index) => ({
+        index,
+        offset_x: supporter_item.get_x() - origin.min_x,
+        offset_z: supporter_item.get_z() - origin.min_z,
+        x: supporter_item.get_x(),
+        z: supporter_item.get_z(),
+        supporter_item
+    }))
+    slots.sort(compare_slots_by_offset)
+    return slots.map((slot, sorted_index) => ({ ...slot, index: sorted_index }))
+}
+
+/**
+ * @param {object} supporter_item
+ * @returns {string}
+ */
+function read_supporter_id(supporter_item)
+{
+    if (typeof supporter_item.get_id === 'function')
+    {
+        return String(supporter_item.get_id() ?? '')
+    }
+    return String(supporter_item._id ?? '')
+}
+
+/**
+ * @param {Supporter_Slot} left
+ * @param {Supporter_Slot} right
+ * @returns {number}
+ */
+function compare_slots_by_offset(left, right)
+{
+    if (!math.eq(left.offset_x, right.offset_x))
+    {
+        return left.offset_x - right.offset_x
+    }
+    if (!math.eq(left.offset_z, right.offset_z))
+    {
+        return left.offset_z - right.offset_z
+    }
+    return read_supporter_id(left.supporter_item)
+        .localeCompare(read_supporter_id(right.supporter_item))
+}
+
+module.exports = build_slot_grid_from_cluster

package/src/Allocation_Optimization/tie_ratio/loose_on_block/compare_group_ids.js

@@ -0,0 +1,20 @@
+/**
+ * Ascending groupId (numeric when both parse as numbers).
+ * @param {string|number} left_group_id
+ * @param {string|number} right_group_id
+ * @returns {number}
+ */
+function compare_group_ids(left_group_id, right_group_id)
+{
+    const left_key = String(left_group_id)
+    const right_key = String(right_group_id)
+    const left_number = Number(left_key)
+    const right_number = Number(right_key)
+    if (!Number.isNaN(left_number) && !Number.isNaN(right_number))
+    {
+        return left_number - right_number
+    }
+    return left_key.localeCompare(right_key)
+}
+
+module.exports = compare_group_ids

package/src/Allocation_Optimization/tie_ratio/loose_on_block/container_with_pending_wall_items.js

@@ -0,0 +1,26 @@
+/**
+ * Merges in-wall allocated items (not yet on the container) into get_allocated_items().
+ * @param {object} container
+ * @param {object[]|undefined} pending_wall_allocated_items
+ * @returns {object}
+ */
+function container_with_pending_wall_items(container, pending_wall_allocated_items)
+{
+    if (!pending_wall_allocated_items || pending_wall_allocated_items.length === 0)
+    {
+        return container
+    }
+
+    const base_get_allocated_items = container.get_allocated_items?.bind(container)
+
+    return {
+        ...container,
+        get_allocated_items()
+        {
+            const merged = base_get_allocated_items ? base_get_allocated_items() : []
+            return [...merged, ...pending_wall_allocated_items]
+        }
+    }
+}
+
+module.exports = container_with_pending_wall_items

package/src/Allocation_Optimization/tie_ratio/loose_on_block/empty_space_is_on_floor.js

@@ -0,0 +1,16 @@
+const math = require('@jetta/number-compare')
+
+/**
+ * @param {object|undefined} empty_space
+ * @returns {boolean}
+ */
+function empty_space_is_on_floor(empty_space)
+{
+    if (empty_space === undefined || typeof empty_space.get_y !== 'function')
+    {
+        return false
+    }
+    return math.le(empty_space.get_y(), 0)
+}
+
+module.exports = empty_space_is_on_floor

package/src/Allocation_Optimization/tie_ratio/loose_on_block/finalize_loose_item_placement.js

@@ -0,0 +1,58 @@
+const realigned_loose_passes_geometry_gates = require('./realigned_loose_geometry_gates')
+const container_with_pending_wall_items = require('./container_with_pending_wall_items')
+
+/**
+ * @param {object} container
+ * @param {object[]|undefined} pending_wall_allocated_items
+ * @returns {void}
+ */
+function sync_container_stacking_checker(container, pending_wall_allocated_items)
+{
+    if (typeof container.commit_allocated_item_for_stacking !== 'function')
+    {
+        return
+    }
+    for (const committed_item of container.get_allocated_items())
+    {
+        container.commit_allocated_item_for_stacking(committed_item)
+    }
+    for (const pending_item of pending_wall_allocated_items ?? [])
+    {
+        container.commit_allocated_item_for_stacking(pending_item)
+    }
+}
+
+/**
+ * Validates stacking and geometric placement for a loose item after realign.
+ * @param {object} allocated_item
+ * @param {object} wall_data
+ * @param {object[]|undefined} pending_wall_allocated_items
+ * @returns {object|undefined}
+ */
+function finalize_loose_item_placement(
+    allocated_item,
+    wall_data,
+    pending_wall_allocated_items
+)
+{
+    const container = wall_data.container
+    sync_container_stacking_checker(container, pending_wall_allocated_items)
+    if (!container.is_a_valid_stacking(allocated_item))
+    {
+        return undefined
+    }
+    const container_view = container_with_pending_wall_items(
+        container,
+        pending_wall_allocated_items
+    )
+    if (!realigned_loose_passes_geometry_gates(container, container_view, allocated_item))
+    {
+        return undefined
+    }
+    return allocated_item
+}
+
+module.exports = {
+    finalize_loose_item_placement,
+    sync_container_stacking_checker
+}

package/src/Allocation_Optimization/tie_ratio/loose_on_block/find_best_generic_supporter_placement.js

@@ -0,0 +1,58 @@
+const footprint_xz_overlap_area = require('./footprint_xz_overlap_area')
+const item_fits_supporter_slot = require('./item_fits_supporter_slot')
+const build_placement_on_generic_supporter = require('./build_placement_on_generic_supporter')
+
+/**
+ * @param {object[]} candidates
+ * @param {object} footprint
+ * @param {object|undefined} slot_state
+ * @param {object} placement_options
+ * @param {object|undefined} container
+ * @returns {{ x: number, y: number, z: number }|undefined}
+ */
+function find_best_generic_supporter_placement(
+    candidates,
+    footprint,
+    slot_state,
+    placement_options,
+    container
+)
+{
+    let best_placement = undefined
+    let best_overlap = -1
+
+    for (const supporter of candidates)
+    {
+        const overlap = footprint_xz_overlap_area(footprint, supporter)
+        if (overlap <= 0 || overlap <= best_overlap)
+        {
+            continue
+        }
+        if (!item_fits_supporter_slot(
+            supporter,
+            placement_options.item_width,
+            placement_options.item_length,
+            placement_options.require_same_area === true
+        ))
+        {
+            continue
+        }
+        const placement = build_placement_on_generic_supporter(
+            candidates,
+            supporter,
+            slot_state,
+            placement_options,
+            container
+        )
+        if (placement === undefined)
+        {
+            continue
+        }
+        best_overlap = overlap
+        best_placement = placement
+    }
+
+    return best_overlap > 0 ? best_placement : undefined
+}
+
+module.exports = find_best_generic_supporter_placement

package/src/Allocation_Optimization/tie_ratio/loose_on_block/find_next_free_slot_index.js

@@ -0,0 +1,119 @@
+const item_fits_supporter_slot = require('./item_fits_supporter_slot')
+const {
+    allocated_item_blocks_slot,
+    allocated_item_occupies_slot,
+    pending_footprint_blocks_slot
+} = require('./slot_footprint_collision')
+const { is_slot_marked_occupied } = require('./loose_on_block_slot_state')
+
+function slot_blocked_by_allocated_items(
+    container,
+    slot,
+    placement_y,
+    placement_options
+)
+{
+    const allocated_items = container.get_allocated_items?.() ?? []
+    const item_width = placement_options?.item_width
+    const item_length = placement_options?.item_length
+    return allocated_items.find(item =>
+    {
+        if (item_width !== undefined && item_length !== undefined)
+        {
+            return allocated_item_blocks_slot(
+                item,
+                slot,
+                placement_y,
+                item_width,
+                item_length
+            )
+        }
+        return allocated_item_occupies_slot(item, slot, placement_y)
+    }) !== undefined
+}
+
+function slot_blocked_by_pending_footprints(
+    slot_state,
+    slot,
+    placement_y,
+    item_width,
+    item_length
+)
+{
+    if (item_width === undefined || item_length === undefined)
+    {
+        return false
+    }
+    return pending_footprint_blocks_slot(
+        slot_state,
+        slot,
+        placement_y,
+        item_width,
+        item_length
+    )
+}
+
+function slot_passes_fit_check(slot, placement_options)
+{
+    if (placement_options === undefined)
+    {
+        return true
+    }
+    return item_fits_supporter_slot(
+        slot.supporter_item,
+        placement_options.item_width,
+        placement_options.item_length,
+        placement_options.require_same_area === true
+    )
+}
+
+/**
+ * @param {object} container
+ * @param {import('./build_slot_grid_from_cluster').Supporter_Slot[]} slot_grid
+ * @param {number} placement_y
+ * @param {object} slot_state
+ * @param {string|number} group_id
+ * @param {object|undefined} placement_options
+ * @returns {number|undefined}
+ */
+function find_next_free_slot_index(
+    container,
+    slot_grid,
+    placement_y,
+    slot_state,
+    group_id,
+    placement_options
+)
+{
+    for (const slot of slot_grid)
+    {
+        if (!slot_passes_fit_check(slot, placement_options))
+        {
+            continue
+        }
+        if (is_slot_marked_occupied(slot_state, group_id, placement_y, slot.index))
+        {
+            continue
+        }
+        if (slot_blocked_by_allocated_items(container, slot, placement_y, placement_options))
+        {
+            continue
+        }
+        const item_width = placement_options?.item_width
+        const item_length = placement_options?.item_length
+        if (slot_blocked_by_pending_footprints(
+            slot_state,
+            slot,
+            placement_y,
+            item_width,
+            item_length
+        ))
+        {
+            continue
+        }
+        return slot.index
+    }
+    return undefined
+}
+
+module.exports = find_next_free_slot_index

package/src/Allocation_Optimization/tie_ratio/loose_on_block/find_supporter_directly_below.js

@@ -0,0 +1,51 @@
+const math = require('@jetta/number-compare')
+const footprint_xz_overlap_area = require('./footprint_xz_overlap_area')
+const loose_footprint_region_from_options = require('./loose_footprint_region_from_options')
+
+/**
+ * @param {object} loose_item
+ * @param {object} supporter
+ * @returns {boolean}
+ */
+function loose_sits_on_supporter_plane(loose_item, supporter)
+{
+    const supporter_top = supporter.get_y() + supporter.get_height()
+    return math.eq(supporter_top, loose_item.get_y())
+}
+
+/**
+ * Finds the allocated item directly below the loose item with the largest XZ overlap.
+ * @param {object} loose_item
+ * @param {object[]} candidate_items
+ * @param {{ loose_origin_x?: number, loose_origin_z?: number, item_width?: number, item_length?: number }|undefined} placement_options
+ * @returns {object|undefined}
+ */
+function find_supporter_directly_below(loose_item, candidate_items, placement_options)
+{
+    const footprint = loose_footprint_region_from_options(loose_item, placement_options)
+    let best_supporter = undefined
+    let best_overlap = -1
+
+    for (const supporter of candidate_items)
+    {
+        if (supporter === loose_item)
+        {
+            continue
+        }
+        if (!loose_sits_on_supporter_plane(loose_item, supporter))
+        {
+            continue
+        }
+        const overlap = footprint_xz_overlap_area(footprint, supporter)
+        if (overlap <= best_overlap)
+        {
+            continue
+        }
+        best_overlap = overlap
+        best_supporter = supporter
+    }
+
+    return best_overlap > 0 ? best_supporter : undefined
+}
+
+module.exports = find_supporter_directly_below

package/src/Allocation_Optimization/tie_ratio/loose_on_block/find_tie_ratio_supporter_cluster.js

@@ -0,0 +1,57 @@
+const math = require('@jetta/number-compare')
+const { build_supporters_by_top_y_index } = require('../supporters_by_top_y_index')
+const { resolve_placement_plane } = require('./tie_ratio_placement_plane')
+const {
+    resolve_supporters,
+    select_best_cluster
+} = require('./tie_ratio_cluster_selection')
+
+/**
+ * Finds the tie-ratio compound cluster directly below an empty space.
+ * @param {object} container
+ * @param {object} empty_space
+ * @param {import('../supporters_by_top_y_index').Supporters_By_Top_Y_Index|undefined} supporters_by_top_y_index
+ * @param {number|undefined} placement_bottom_y
+ * @param {{ item_height?: number }|undefined} placement_options
+ * @returns {{ group_id: string|number, orientation: '3_2'|'2_3', items: object[] }|undefined}
+ */
+function find_tie_ratio_supporter_cluster(
+    container,
+    empty_space,
+    supporters_by_top_y_index,
+    placement_bottom_y,
+    placement_options
+)
+{
+    if (!empty_space)
+    {
+        return undefined
+    }
+
+    const space_bottom = resolve_placement_plane(
+        container,
+        empty_space,
+        supporters_by_top_y_index,
+        placement_bottom_y,
+        placement_options
+    )
+    if (space_bottom === undefined || math.le(space_bottom, 0))
+    {
+        return undefined
+    }
+
+    return select_best_cluster(
+        resolve_supporters(
+            container,
+            supporters_by_top_y_index,
+            space_bottom,
+            empty_space,
+            placement_options
+        ),
+        empty_space,
+        placement_options
+    )
+}
+
+module.exports = find_tie_ratio_supporter_cluster
+module.exports.build_supporters_by_top_y_index = build_supporters_by_top_y_index

package/src/Allocation_Optimization/tie_ratio/loose_on_block/footprint_xz_overlap_area.js

@@ -0,0 +1,26 @@
+const axis_overlap_length = require('./axis_overlap_length')
+
+/**
+ * Returns XZ footprint overlap area between two axis-aligned boxes.
+ * @param {object} left - getters x, z, width, length
+ * @param {object} right - getters x, z, width, length
+ * @returns {number}
+ */
+function footprint_xz_overlap_area(left, right)
+{
+    const x_overlap = axis_overlap_length(
+        left.get_x(),
+        left.get_x() + left.get_width(),
+        right.get_x(),
+        right.get_x() + right.get_width()
+    )
+    const z_overlap = axis_overlap_length(
+        left.get_z(),
+        left.get_z() + left.get_length(),
+        right.get_z(),
+        right.get_z() + right.get_length()
+    )
+    return x_overlap * z_overlap
+}
+
+module.exports = footprint_xz_overlap_area

package/src/Allocation_Optimization/tie_ratio/loose_on_block/item_fits_supporter_slot.js

@@ -0,0 +1,22 @@
+const math = require('@jetta/number-compare')
+
+/**
+ * Checks whether a loose item footprint fits a tie-ratio supporter slot.
+ * @param {object} supporter_item
+ * @param {number} item_width
+ * @param {number} item_length
+ * @param {boolean} require_same_area
+ * @returns {boolean}
+ */
+function item_fits_supporter_slot(supporter_item, item_width, item_length, require_same_area)
+{
+    const supporter_width = supporter_item.get_width()
+    const supporter_length = supporter_item.get_length()
+    if (require_same_area)
+    {
+        return math.eq(item_width, supporter_width) && math.eq(item_length, supporter_length)
+    }
+    return math.le(item_width, supporter_width) && math.le(item_length, supporter_length)
+}
+
+module.exports = item_fits_supporter_slot

package/src/Allocation_Optimization/tie_ratio/loose_on_block/loose_footprint_region_from_options.js

@@ -0,0 +1,24 @@
+/**
+ * Footprint region for overlap scoring before snap (assign origin + dimensions).
+ * @param {object} loose_item
+ * @param {{ loose_origin_x?: number, loose_origin_z?: number, item_width?: number, item_length?: number }|undefined} placement_options
+ * @returns {object}
+ */
+function loose_footprint_region_from_options(loose_item, placement_options)
+{
+    if (placement_options?.loose_origin_x !== undefined
+        && placement_options?.loose_origin_z !== undefined
+        && placement_options?.item_width !== undefined
+        && placement_options?.item_length !== undefined)
+    {
+        return {
+            get_x: () => placement_options.loose_origin_x,
+            get_z: () => placement_options.loose_origin_z,
+            get_width: () => placement_options.item_width,
+            get_length: () => placement_options.item_length
+        }
+    }
+    return loose_item
+}
+
+module.exports = loose_footprint_region_from_options

package/src/Allocation_Optimization/tie_ratio/loose_on_block/loose_item_fits_inside_container.js

@@ -0,0 +1,21 @@
+const box_fits_inside_container = require('./box_fits_inside_container')
+
+/**
+ * @param {object} container - Space with width, height, length getters
+ * @param {object} allocated_item
+ * @returns {boolean}
+ */
+function loose_item_fits_inside_container(container, allocated_item)
+{
+    return box_fits_inside_container(
+        container,
+        allocated_item.get_x(),
+        allocated_item.get_y(),
+        allocated_item.get_z(),
+        allocated_item.get_width(),
+        allocated_item.get_height(),
+        allocated_item.get_length()
+    )
+}
+
+module.exports = loose_item_fits_inside_container

package/src/Allocation_Optimization/tie_ratio/loose_on_block/loose_item_has_geometric_support.js

@@ -0,0 +1,21 @@
+const math = require('@jetta/number-compare')
+const find_supporter_directly_below = require('./find_supporter_directly_below')
+
+/**
+ * @param {object} container_view - object with get_allocated_items()
+ * @param {object} loose_item
+ * @returns {boolean}
+ */
+function loose_item_has_geometric_support(container_view, loose_item)
+{
+    if (math.le(loose_item.get_y(), 0))
+    {
+        return true
+    }
+
+    const candidates = container_view.get_allocated_items?.() ?? []
+    const supporter = find_supporter_directly_below(loose_item, candidates)
+    return supporter !== undefined
+}
+
+module.exports = loose_item_has_geometric_support