@jetta/blocks-allocator 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,119 @@
+const math = require('@jetta/number-compare')
+const { supporters_at_top_y } = require('../supporters_by_top_y_index')
+const { is_tie_ratio_supporter } = require('./tie_ratio_supporter_predicate')
+const { footprint_overlap_score } = require('./tie_ratio_footprint_overlap')
+const compare_group_ids = require('./compare_group_ids')
+
+function group_supporters_by_group_id(supporter_list)
+{
+    const groups = new Map()
+    for (const item of supporter_list)
+    {
+        if (!is_tie_ratio_supporter(item))
+        {
+            continue
+        }
+        const group_id = item.get_group_id()
+        if (!groups.has(group_id))
+        {
+            groups.set(group_id, [])
+        }
+        groups.get(group_id).push(item)
+    }
+    return groups
+}
+
+/**
+ * @param {object} item
+ * @param {number} space_bottom
+ * @returns {boolean}
+ */
+function is_supporter_at_placement_plane(item, space_bottom)
+{
+    return math.eq(item.get_y() + item.get_height(), space_bottom)
+}
+
+/**
+ * @param {object} container
+ * @param {import('../supporters_by_top_y_index').Supporters_By_Top_Y_Index|undefined} supporters_by_top_y_index
+ * @param {number} space_bottom
+ * @param {object} empty_space
+ * @param {object|undefined} placement_options
+ * @returns {object[]}
+ */
+function resolve_supporters(
+    container,
+    supporters_by_top_y_index,
+    space_bottom,
+    empty_space,
+    placement_options
+)
+{
+    if (supporters_by_top_y_index !== undefined)
+    {
+        return supporters_at_top_y(supporters_by_top_y_index, space_bottom)
+    }
+    return (container.get_allocated_items?.() ?? []).filter(item =>
+        is_tie_ratio_supporter(item)
+        && is_supporter_at_placement_plane(item, space_bottom)
+        && footprint_overlap_score(item, empty_space, placement_options) > 0
+    )
+}
+
+/**
+ * @param {number} score
+ * @param {number} best_score
+ * @param {string|number} group_id
+ * @param {{ group_id: string|number }|undefined} best_cluster
+ * @returns {boolean}
+ */
+function should_replace_best_cluster(score, best_score, group_id, best_cluster)
+{
+    if (math.eq(score, best_score) && best_cluster !== undefined)
+    {
+        return compare_group_ids(group_id, best_cluster.group_id) < 0
+    }
+    return score > best_score
+}
+
+/**
+ * @param {object[]} supporter_list
+ * @param {object} empty_space
+ * @param {object|undefined} placement_options
+ * @returns {{ group_id: string|number, orientation: string, items: object[] }|undefined}
+ */
+function select_best_cluster(supporter_list, empty_space, placement_options)
+{
+    const groups = group_supporters_by_group_id(supporter_list)
+    let best_cluster = undefined
+    let best_score = -1
+
+    for (const [group_id, items] of groups.entries())
+    {
+        if (items.length < 2)
+        {
+            continue
+        }
+        const score = items.reduce(
+            (total, item) => total + footprint_overlap_score(item, empty_space, placement_options),
+            0
+        )
+        if (!should_replace_best_cluster(score, best_score, group_id, best_cluster))
+        {
+            continue
+        }
+        best_score = score
+        best_cluster = {
+            group_id,
+            orientation: items[0].get_tie_ratio_orientation(),
+            items
+        }
+    }
+
+    return best_score > 0 ? best_cluster : undefined
+}
+
+module.exports = {
+    resolve_supporters,
+    select_best_cluster
+}

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

@@ -0,0 +1,56 @@
+const axis_overlap_length = require('./axis_overlap_length')
+
+/**
+ * @param {object} item
+ * @param {object} region
+ * @returns {number}
+ */
+function footprint_overlap_on_space(item, region)
+{
+    const x_overlap = axis_overlap_length(
+        item.get_x(),
+        item.get_x() + item.get_width(),
+        region.get_x(),
+        region.get_x() + region.get_width()
+    )
+    const z_overlap = axis_overlap_length(
+        item.get_z(),
+        item.get_z() + item.get_length(),
+        region.get_z(),
+        region.get_z() + region.get_length()
+    )
+    return x_overlap * z_overlap
+}
+
+/**
+ * @param {object} item
+ * @param {object} empty_space
+ * @param {{ loose_origin_x?: number, loose_origin_z?: number, item_width?: number, item_length?: number }|undefined} placement_options
+ * @returns {number}
+ */
+function footprint_overlap_score(item, empty_space, placement_options)
+{
+    const empty_score = footprint_overlap_on_space(item, empty_space)
+    if (empty_score > 0)
+    {
+        return empty_score
+    }
+    if (placement_options?.loose_origin_x === undefined
+        || placement_options?.loose_origin_z === undefined
+        || placement_options?.item_width === undefined
+        || placement_options?.item_length === undefined)
+    {
+        return 0
+    }
+    return footprint_overlap_on_space(item, {
+        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
+    })
+}
+
+module.exports = {
+    footprint_overlap_on_space,
+    footprint_overlap_score
+}

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

@@ -0,0 +1,109 @@
+const math = require('@jetta/number-compare')
+const { is_tie_ratio_supporter } = require('./tie_ratio_supporter_predicate')
+const { footprint_overlap_score } = require('./tie_ratio_footprint_overlap')
+
+function list_overlapping_tie_supporters(
+    container,
+    supporters_by_top_y_index,
+    empty_space,
+    placement_options
+)
+{
+    const overlaps = (item) => footprint_overlap_score(item, empty_space, placement_options) > 0
+    if (supporters_by_top_y_index !== undefined)
+    {
+        const merged = []
+        for (const bucket of supporters_by_top_y_index.bucket_list)
+        {
+            merged.push(...bucket.items)
+        }
+        return merged.filter(item => is_tie_ratio_supporter(item) && overlaps(item))
+    }
+    return (container.get_allocated_items?.() ?? []).filter(item =>
+        is_tie_ratio_supporter(item) && overlaps(item)
+    )
+}
+
+/**
+ * @param {object} container
+ * @param {import('../supporters_by_top_y_index').Supporters_By_Top_Y_Index|undefined} supporters_by_top_y_index
+ * @param {object} empty_space
+ * @param {object|undefined} placement_options
+ * @returns {number[]}
+ */
+function distinct_supporter_tops_overlapping(
+    container,
+    supporters_by_top_y_index,
+    empty_space,
+    placement_options
+)
+{
+    const supporters = list_overlapping_tie_supporters(
+        container,
+        supporters_by_top_y_index,
+        empty_space,
+        placement_options
+    )
+    const tops = supporters.map(item => item.get_y() + item.get_height())
+    return [...new Set(tops)].sort((left, right) => left - right)
+}
+
+/**
+ * @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 {object|undefined} placement_options
+ * @returns {number|undefined}
+ */
+function resolve_placement_plane(
+    container,
+    empty_space,
+    supporters_by_top_y_index,
+    placement_bottom_y,
+    placement_options
+)
+{
+    const empty_bottom = empty_space.get_y()
+    if (math.gt(empty_bottom, 0))
+    {
+        return empty_bottom
+    }
+
+    const candidate_tops = distinct_supporter_tops_overlapping(
+        container,
+        supporters_by_top_y_index,
+        empty_space,
+        placement_options
+    )
+    if (candidate_tops.length === 0)
+    {
+        return placement_bottom_y
+    }
+
+    if (placement_bottom_y !== undefined && math.gt(placement_bottom_y, 0))
+    {
+        const exact_top = candidate_tops.find(top => math.eq(top, placement_bottom_y))
+        if (exact_top !== undefined)
+        {
+            return exact_top
+        }
+
+        const item_height = placement_options?.item_height ?? 0
+        const loose_top = placement_bottom_y + item_height
+        const supporting_tops = candidate_tops.filter(top =>
+            math.le(top, loose_top)
+        )
+        if (supporting_tops.length > 0)
+        {
+            return supporting_tops[supporting_tops.length - 1]
+        }
+    }
+
+    return candidate_tops[candidate_tops.length - 1]
+}
+
+module.exports = {
+    resolve_placement_plane,
+    list_overlapping_tie_supporters
+}

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

@@ -0,0 +1,23 @@
+/**
+ * @param {string|number|undefined|null} group_id
+ * @returns {boolean}
+ */
+function has_group_id(group_id)
+{
+    return group_id !== undefined && group_id !== null
+}
+
+/**
+ * @param {object} item
+ * @returns {boolean}
+ */
+function is_tie_ratio_supporter(item)
+{
+    const orientation = item.get_tie_ratio_orientation?.()
+    return has_group_id(item.get_group_id()) && (orientation === '3_2' || orientation === '2_3')
+}
+
+module.exports = {
+    has_group_id,
+    is_tie_ratio_supporter
+}

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

@@ -0,0 +1,62 @@
+const find_next_free_slot_index = require('./find_next_free_slot_index')
+const {
+    mark_slot_occupied,
+    register_pending_footprint
+} = require('./loose_on_block_slot_state')
+
+/**
+ * @param {object} container
+ * @param {object} slot
+ * @param {number} placement_y
+ * @param {object} slot_state
+ * @param {{ group_id: string|number, items: object[] }} cluster
+ * @param {object|undefined} placement_options
+ * @returns {{ x: number, y: number, z: number, slot_index: number, group_id: string|number }|undefined}
+ */
+function try_tie_ratio_slot_placement(
+    container,
+    slot,
+    placement_y,
+    slot_state,
+    cluster,
+    placement_options
+)
+{
+    if (find_next_free_slot_index(
+        container,
+        [slot],
+        placement_y,
+        slot_state,
+        cluster.group_id,
+        placement_options
+    ) === undefined)
+    {
+        return undefined
+    }
+
+    const placement = {
+        x: slot.x,
+        y: placement_y,
+        z: slot.z,
+        slot_index: slot.index,
+        group_id: cluster.group_id
+    }
+    mark_slot_occupied(slot_state, cluster.group_id, placement_y, slot.index)
+    if (placement_options?.item_width !== undefined
+        && placement_options?.item_length !== undefined
+        && placement_options?.item_height !== 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 = try_tie_ratio_slot_placement

package/src/Allocation_Optimization/tie_ratio/snap_stacked_items_to_floor_footprints.js

@@ -0,0 +1,138 @@
+const math = require('@jetta/number-compare')
+const No_Suitable_Item_Exception = require('../block_builder/exceptions/No_Suitable_Item_Exception')
+const { ALLOCATOR_MESSAGE } = require('../../messages/Allocator_Message')
+
+const FLOOR_Y = 0
+
+/**
+ * Copies floor (x, z) onto stacked items so each sits on a unique compatible footprint.
+ * @param {object[]} stacked_items
+ * @param {object[]} allocated_items
+ * @returns {object[]}
+ */
+function snap_stacked_items_to_floor_footprints(stacked_items, allocated_items)
+{
+    if (!layer_is_elevated(stacked_items))
+    {
+        return stacked_items
+    }
+    const remaining_floor = collect_overlapping_floor_items(stacked_items, allocated_items)
+    return stacked_items.map(stacked => take_floor_twin(stacked, remaining_floor, allocated_items))
+}
+
+function layer_is_elevated(items)
+{
+    return items.some(item => math.gt(item.get_y(), FLOOR_Y))
+}
+
+function collect_overlapping_floor_items(stacked_items, allocated_items)
+{
+    const aabb = cluster_xz_aabb(stacked_items)
+    return allocated_items.filter(item => math.eq(item.get_y(), FLOOR_Y) && xz_overlaps_aabb(item, aabb))
+}
+
+function take_floor_twin(stacked, remaining_floor, allocated_items)
+{
+    const index = find_free_floor_twin_index(stacked, remaining_floor, allocated_items)
+    if (index < 0)
+    {
+        throw new No_Suitable_Item_Exception(ALLOCATOR_MESSAGE.NO_FLOOR_FOOTPRINT_TWIN)
+    }
+    const [floor] = remaining_floor.splice(index, 1)
+    return copy_xz(stacked, floor)
+}
+
+function find_free_floor_twin_index(stacked, remaining_floor, allocated_items)
+{
+    let best_index = -1
+    let best_distance = Infinity
+    for (let index = 0; index < remaining_floor.length; index++)
+    {
+        const floor = remaining_floor[index]
+        if (!is_free_matching_floor(stacked, floor, allocated_items))
+        {
+            continue
+        }
+        const distance = xz_distance_squared(stacked, floor)
+        if (distance < best_distance)
+        {
+            best_distance = distance
+            best_index = index
+        }
+    }
+    return best_index
+}
+
+function is_free_matching_floor(stacked, floor, allocated_items)
+{
+    return footprints_match(stacked, floor) && !floor_has_elevated_occupant(floor, stacked, allocated_items)
+}
+
+function xz_distance_squared(stacked, floor)
+{
+    const dx = stacked.get_x() - floor.get_x()
+    const dz = stacked.get_z() - floor.get_z()
+    return dx * dx + dz * dz
+}
+
+function floor_has_elevated_occupant(floor, stacked, allocated_items)
+{
+    const destination = {
+        get_x: () => floor.get_x(),
+        get_y: () => stacked.get_y(),
+        get_z: () => floor.get_z(),
+        get_width: () => stacked.get_width(),
+        get_height: () => stacked.get_height(),
+        get_length: () => stacked.get_length()
+    }
+    return allocated_items.some(item => elevated_item_overlaps(item, destination))
+}
+
+function elevated_item_overlaps(item, destination)
+{
+    return math.gt(item.get_y(), FLOOR_Y) && items_overlap_volume(item, destination)
+}
+
+function items_overlap_volume(item_a, item_b)
+{
+    const overlap_x = Math.min(item_a.get_x() + item_a.get_width(), item_b.get_x() + item_b.get_width())
+        - Math.max(item_a.get_x(), item_b.get_x())
+    const overlap_y = Math.min(item_a.get_y() + item_a.get_height(), item_b.get_y() + item_b.get_height())
+        - Math.max(item_a.get_y(), item_b.get_y())
+    const overlap_z = Math.min(item_a.get_z() + item_a.get_length(), item_b.get_z() + item_b.get_length())
+        - Math.max(item_a.get_z(), item_b.get_z())
+    return overlap_x > 1e-6 && overlap_y > 1e-6 && overlap_z > 1e-6
+}
+
+function footprints_match(stacked, floor)
+{
+    return math.eq(stacked.get_width(), floor.get_width())
+        && math.eq(stacked.get_length(), floor.get_length())
+}
+
+function copy_xz(stacked, floor)
+{
+    stacked.x = floor.get_x()
+    stacked.z = floor.get_z()
+    return stacked
+}
+
+function cluster_xz_aabb(items)
+{
+    return {
+        min_x: Math.min(...items.map(item => item.get_x())),
+        max_x: Math.max(...items.map(item => item.get_x() + item.get_width())),
+        min_z: Math.min(...items.map(item => item.get_z())),
+        max_z: Math.max(...items.map(item => item.get_z() + item.get_length()))
+    }
+}
+
+function xz_overlaps_aabb(item, aabb)
+{
+    const max_x = item.get_x() + item.get_width()
+    const max_z = item.get_z() + item.get_length()
+    return item.get_x() < aabb.max_x && aabb.min_x < max_x
+        && item.get_z() < aabb.max_z && aabb.min_z < max_z
+}
+
+module.exports = snap_stacked_items_to_floor_footprints

package/src/Allocation_Optimization/tie_ratio/supporters_by_top_y_index.js

@@ -0,0 +1,78 @@
+const math = require('@jetta/number-compare')
+
+/**
+ * @typedef {object} Supporters_By_Top_Y_Index
+ * @property {Array<{ top_y: number, items: object[] }>} bucket_list
+ */
+
+/**
+ * Groups allocated items by top Y for fast supporter lookup.
+ * Buckets stay sorted by top_y; float-equal levels merge via math.eq.
+ * @param {object[]} allocated_items
+ * @returns {Supporters_By_Top_Y_Index}
+ */
+function build_supporters_by_top_y_index(allocated_items)
+{
+    const bucket_list = []
+    for (const item of allocated_items)
+    {
+        const top_y = item.get_y() + item.get_height()
+        const slot = bucket_slot_for_top_y(bucket_list, top_y)
+        if (slot >= 0)
+        {
+            bucket_list[slot].items.push(item)
+            continue
+        }
+        bucket_list.splice(~slot, 0, { top_y, items: [item] })
+    }
+    return { bucket_list }
+}
+
+/**
+ * Returns allocated items whose top Y equals the requested level.
+ * @param {Supporters_By_Top_Y_Index} index
+ * @param {number} top_y
+ * @returns {object[]}
+ */
+function supporters_at_top_y(index, top_y)
+{
+    const slot = bucket_slot_for_top_y(index.bucket_list, top_y)
+    if (slot < 0)
+    {
+        return []
+    }
+    return index.bucket_list[slot].items
+}
+
+/**
+ * Lower-bound binary search for a bucket by top_y (math.eq for matches).
+ * @param {Array<{ top_y: number, items: object[] }>} bucket_list
+ * @param {number} top_y
+ * @returns {number} Found index (>= 0), or ~insertion_index when absent
+ */
+function bucket_slot_for_top_y(bucket_list, top_y)
+{
+    let low = 0
+    let high = bucket_list.length
+    while (low < high)
+    {
+        const mid = (low + high) >> 1
+        const mid_top_y = bucket_list[mid].top_y
+        if (math.eq(mid_top_y, top_y))
+        {
+            return mid
+        }
+        if (mid_top_y < top_y)
+        {
+            low = mid + 1
+            continue
+        }
+        high = mid
+    }
+    return ~low
+}
+
+module.exports = {
+    build_supporters_by_top_y_index,
+    supporters_at_top_y
+}

package/src/Allocation_Optimization/tie_ratio/tie_ratio_orientation_below_empty_space.js

@@ -0,0 +1,89 @@
+const find_orientation_below_space = require('./find_orientation_below_space')
+const { build_supporters_by_top_y_index } = require('./supporters_by_top_y_index')
+const { collect_tie_ratio_orientations_below_footprint } = require('./collect_tie_ratio_orientations_below_footprint')
+
+/**
+ * Resolves tie-ratio orientation of the compound supporter under an empty space footprint.
+ * @param {object} filter_like
+ * @param {object} filter_like.container
+ * @param {object|undefined} filter_like.empty_space
+ * @param {import('./supporters_by_top_y_index').Supporters_By_Top_Y_Index|undefined} [filter_like.supporters_by_top_y_index]
+ * @returns {'3_2'|'2_3'|undefined}
+ */
+function tie_ratio_orientation_below_empty_space(filter_like)
+{
+    const orientations = tie_ratio_orientations_below_empty_space(filter_like)
+    if (orientations.length !== 1)
+    {
+        return undefined
+    }
+    return orientations[0]
+}
+
+/**
+ * @param {object} filter_like
+ * @returns {Array<'3_2'|'2_3'>}
+ */
+function tie_ratio_orientations_below_empty_space(filter_like)
+{
+    const empty_space = filter_like.empty_space
+    if (empty_space === undefined || empty_space.get_y() <= 0)
+    {
+        return []
+    }
+
+    const container = filter_like.container
+    const allocated_items = container.get_allocated_items?.() ?? []
+    const supporters_by_top_y_index = filter_like.supporters_by_top_y_index
+        ?? build_supporters_by_top_y_index(allocated_items)
+
+    return collect_tie_ratio_orientations_below_footprint(
+        container,
+        empty_space,
+        supporters_by_top_y_index
+    )
+}
+
+/**
+ * @param {object} filter_like
+ * @returns {boolean}
+ */
+function empty_space_stacks_on_tie_ratio_supporter(filter_like)
+{
+    return tie_ratio_orientations_below_empty_space(filter_like).length > 0
+}
+
+/**
+ * @param {object} container
+ * @param {{ x: number, y: number, z: number }} placement_origin
+ * @param {number} block_width
+ * @param {number} block_length
+ * @param {import('./supporters_by_top_y_index').Supporters_By_Top_Y_Index|undefined} [supporters_by_top_y_index]
+ * @returns {'3_2'|'2_3'|undefined}
+ */
+function tie_ratio_orientation_below_placement(
+    container,
+    placement_origin,
+    block_width,
+    block_length,
+    supporters_by_top_y_index
+)
+{
+    const footprint_space = {
+        get_y: () => placement_origin.y,
+        get_x: () => placement_origin.x,
+        get_z: () => placement_origin.z,
+        get_width: () => block_width,
+        get_length: () => block_length
+    }
+    return find_orientation_below_space(
+        container,
+        footprint_space,
+        supporters_by_top_y_index
+    )
+}
+
+module.exports = tie_ratio_orientation_below_empty_space
+module.exports.tie_ratio_orientations_below_empty_space = tie_ratio_orientations_below_empty_space
+module.exports.empty_space_stacks_on_tie_ratio_supporter = empty_space_stacks_on_tie_ratio_supporter
+module.exports.tie_ratio_orientation_below_placement = tie_ratio_orientation_below_placement