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

package/src/Allocation_Optimization/preferential_blocks/key_item/Key_Item_Mapper.js

@@ -0,0 +1,49 @@
+const Cargo_Profile = require('../../../models/Cargo_Profile')
+const Cant_Stack_It_Self = require('./rules/Cant_Stack_It_Self')
+const Almost_Unique_Item = require('./rules/Almost_Unique_Item')
+/**
+ * @class Key_Item_Mapper
+ * @description Manages and applies rules to identify "key items" within a set of items.
+ * Key items are those that have specific allocation constraints or preferences.
+ * @see {@link file://c:/Users/amatsukan/jetta/blocks-wall-allocation/doc/how_to_add_a_key_item_rule.md}
+ */
+class Key_Item_Mapper
+{
+    #rules
+
+    /**
+     * @constructor
+     * @description Initializes the Key_Item_Mapper with a predefined set of rules.
+     */
+    constructor()
+    {
+        this.#rules = [
+            new Cant_Stack_It_Self(),
+            new Almost_Unique_Item()
+        ]
+    }
+
+    /**
+     * @method filter_key_items
+     * @description Filters a given array of items, returning only those that are identified as "key items"
+     * based on the applied rules. An item is considered a key item if at least one rule identifies it as such.
+     *
+     * @param {object} container - The container object against which the rules are evaluated.
+     * @param {Array<object>} items - An array of item objects to be filtered.
+     * @returns {Array<object>} An array containing only the key items.
+     */
+    filter_key_items(container, items)
+    {
+        if (!Cargo_Profile.enable_key_item_mapping())
+        {
+            return []
+        }
+
+        const apply_rules = (item) =>
+        {
+            return this.#rules.some(rule => rule.is_key_item(container, item, items))
+        }
+        return items.filter(apply_rules)
+    }
+}
+module.exports = Key_Item_Mapper

package/src/Allocation_Optimization/preferential_blocks/key_item/rules/Almost_Unique_Item.js

@@ -0,0 +1,31 @@
+const Rule_Interface = require('./Rule_Interface')
+
+/**
+ * @class Almost_Unique_Item
+ * @augments Rule_Interface
+ * @description Implements a rule to identify an item as a "key item" if it is unique in the list of available items.
+ */
+class Almost_Unique_Item extends Rule_Interface
+{
+    /**
+     * Checks if a given item is a key item within the context of a container.
+     *
+     * Almost_Unique_Item is item amount < 3
+     *
+     * @param {Container} container - The container object (e.g., from `src\models\Container.js`).
+     * @param {Allocation_Item} item - The item object, (e.g., from `src/models/Allocation_Item`)
+     * @param {Array<Allocation_Item>} item_list - A list of all available items to be allocated.
+     * @returns {boolean} - Returns `true` if the item is considered a key item, `false` otherwise.
+     * @throws {Error} - Throws an error if the method is not overridden by the extended class.
+     */
+    is_key_item(container, item, item_list)
+    {
+        // An item is considered a "key item" by this rule if it is the only one of its kind in the list.
+        return item_list.filter(i => i.get_hash() === item.get_hash()).length < 3
+    }
+}
+
+/**
+ * @module Almost_Unique_Item
+ */
+module.exports = Almost_Unique_Item

package/src/Allocation_Optimization/preferential_blocks/key_item/rules/Cant_Stack_It_Self.js

@@ -0,0 +1,68 @@
+const Rule_Interface = require('./Rule_Interface')
+
+/**
+ * @class Cant_Stack_It_Self
+ * @augments Rule_Interface
+ * @description Implements a rule to identify "key items" that cannot be stacked upon or have specific stacking restrictions.
+ */
+
+class Cant_Stack_It_Self extends Rule_Interface
+{
+    /**
+     * Checks if a given item is a key item within the context of a container.
+     * For this rule, an item is considered a key item if its `empilhamentoMaximo` property is 0,
+     * meaning it cannot be stacked upon.
+     *
+     * @param {Transport} transport - The transport object (e.g., from `src/models/transport/Transport.js`).
+     * @param {Allocation_Item} item - The item object, (e.g., from `src/models/Allocation_Item`)
+     * @returns {boolean} - Returns `true` if the item's `empilhamentoMaximo` is 0, `false` otherwise.
+     */
+    is_key_item(transport, item)
+    {
+        const containers = [ ... transport.get_containers().values() ]
+        const container_heights = containers.map(container => container.get_height())
+        const bigger_container_height = Math.max(...container_heights)
+        const item_height = get_item_max_height(item)
+        const item_max_stack = item.empilhamentoMaximo ? item.empilhamentoMaximo : item.get_stacking_info().max_stacking
+        const item_weight = item.peso ? item.peso : item.get_stacking_info().weight
+        const item_max_load_weight = item.pesoMaxSuportado ? item.pesoMaxSuportado : item.get_stacking_info().supported_weight
+
+        const conditions =
+        [
+            item_max_load_weight < item_weight,
+            item_max_stack === 0,
+            item_height * 2 > bigger_container_height
+        ]
+        return conditions.some(condition => condition)
+    }
+}
+
+const get_height = (item) =>
+{
+    if (item.altura !== undefined)
+    {
+        return item.altura
+    }
+    if (typeof item.get_height === 'function')
+    {
+        return item.get_height()
+    }
+    throw Error('Not possible to find item height')
+}
+
+function get_item_max_height(item)
+{
+    const rotation_options      = item.get_all_rotated_options()
+    if (rotation_options === undefined || rotation_options.length === 0)
+    {
+        throw new Error('item has no rotations')
+    }
+    const item_possible_heights = rotation_options.map(get_height)
+    const item_height           = Math.max(...item_possible_heights)
+    return item_height
+}
+
+/**
+ * @module Cant_Stack_It_Self
+ */
+module.exports = Cant_Stack_It_Self

package/src/Allocation_Optimization/preferential_blocks/key_item/rules/Rule_Interface.js

@@ -0,0 +1,26 @@
+/**
+ * @interface Rule_Interface
+ * @description Defines the contract for rules that identify "key items" within an allocation context.
+ * All concrete rule implementations must extend this interface and implement the `is_key_item` method.
+ * @see {@link file://c:/Users/amatsukan/jetta/blocks-wall-allocation/doc/how_to_add_a_key_item_rule.md}
+ */
+class Rule_Interface
+{
+
+    /**
+     * Checks if a given item is a key item within the context of a container.
+     * This is a pure virtual method that must be implemented by any class extending Rule_Interface.
+     *
+     * @param {Container} container - The container object (e.g., from `src\models\Container.js`).
+     * @param {Allocation_Item} item - The item object, (e.g., from `src/models/Allocation_Item`)
+     * @param {Array<Allocation_Item>} item_list - A list of all available items to be allocated.
+     * @returns {boolean} - Returns `true` if the item is considered a key item, `false` otherwise.
+     * @throws {Error} - Throws an error if the method is not overridden by the extended class.
+     */
+    is_key_item(container, item, item_list)
+    {
+        throw new Error('Not overrided pure virtual method, please implement on your extended class')
+    }
+}
+
+module.exports = Rule_Interface

package/src/Allocation_Optimization/tie_ratio/Tie_Ratio_Intercalation_State.js

@@ -0,0 +1,49 @@
+const ORIENTATION_SEQUENCE = ['3_2', '2_3']
+
+/**
+ * Tracks required tie-ratio orientation for intercalated wall allocation per container.
+ */
+class Tie_Ratio_Intercalation_State
+{
+    #allocate_intercalated
+    #next_orientation_index = 0
+
+    /**
+     * @param {boolean} allocate_intercalated - Whether intercalation alternation is enabled.
+     */
+    constructor(allocate_intercalated)
+    {
+        this.#allocate_intercalated = allocate_intercalated === true
+    }
+
+    reset()
+    {
+        this.#next_orientation_index = 0
+    }
+
+    /**
+     * @returns {'3_2'|'2_3'|null} Required orientation, or null when intercalation is disabled.
+     */
+    get_required_orientation()
+    {
+        if (!this.#allocate_intercalated)
+        {
+            return null
+        }
+        return ORIENTATION_SEQUENCE[this.#next_orientation_index]
+    }
+
+    /**
+     * Toggles orientation after a wall that placed at least one tie-ratio block.
+     */
+    advance_after_tie_ratio_wall()
+    {
+        if (!this.#allocate_intercalated)
+        {
+            return
+        }
+        this.#next_orientation_index = (this.#next_orientation_index + 1) % ORIENTATION_SEQUENCE.length
+    }
+}
+
+module.exports = Tie_Ratio_Intercalation_State

package/src/Allocation_Optimization/tie_ratio/Tie_Ratio_Orientation_Filter.js

@@ -0,0 +1,33 @@
+const Block_Filter_Interface = require('../../space_and_block_chooser/blocks_filters/Block_Filter_Interface')
+const Cargo_Profile = require('../../models/Cargo_Profile')
+const filter_blocks_by_orientation = require('./filter_blocks_by_orientation')
+const { empty_space_stacks_on_tie_ratio_supporter } = require('./tie_ratio_orientation_below_empty_space')
+
+/**
+ * Post-selection filter: tie-ratio blocks must match the next intercalated orientation along Z.
+ */
+module.exports = class Tie_Ratio_Orientation_Filter extends Block_Filter_Interface
+{
+    static run(filter_data)
+    {
+        if (!Cargo_Profile.allocate_intercalated())
+        {
+            return filter_data.block_list
+        }
+
+        if (empty_space_stacks_on_tie_ratio_supporter(filter_data))
+        {
+            return filter_data.block_list
+        }
+
+        const required_orientation = filter_data.tie_ratio_intercalation_state
+            ?.get_required_orientation() ?? null
+
+        if (required_orientation === null)
+        {
+            return filter_data.block_list
+        }
+
+        return filter_blocks_by_orientation(filter_data.block_list, required_orientation)
+    }
+}

package/src/Allocation_Optimization/tie_ratio/Tie_Ratio_Vertical_Stack_Filter.js

@@ -0,0 +1,20 @@
+const Block_Filter_Interface = require('../../space_and_block_chooser/blocks_filters/Block_Filter_Interface')
+const filter_blocks_by_orientation = require('./filter_blocks_by_orientation')
+const tie_ratio_orientation_below_empty_space = require('./tie_ratio_orientation_below_empty_space')
+
+/**
+ * Post-selection filter: stacked tie-ratio blocks must match orientation below the space.
+ */
+module.exports = class Tie_Ratio_Vertical_Stack_Filter extends Block_Filter_Interface
+{
+    static run(filter_data)
+    {
+        const stack_orientation = tie_ratio_orientation_below_empty_space(filter_data)
+        if (stack_orientation === undefined)
+        {
+            return filter_data.block_list
+        }
+
+        return filter_blocks_by_orientation(filter_data.block_list, stack_orientation)
+    }
+}

package/src/Allocation_Optimization/tie_ratio/collect_tie_ratio_orientations_below_footprint.js

@@ -0,0 +1,64 @@
+const math = require('@jetta/number-compare')
+const { supporters_at_top_y } = require('./supporters_by_top_y_index')
+const { footprint_overlap_on_space } = require('./loose_on_block/tie_ratio_footprint_overlap')
+const {
+    build_tie_ratio_orientation_by_group_id,
+    tie_ratio_orientation_from_item
+} = require('./tie_ratio_orientation_from_group')
+
+/**
+ * @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
+ * @returns {Array<'3_2'|'2_3'>}
+ */
+function collect_tie_ratio_orientations_below_footprint(
+    container,
+    empty_space,
+    supporters_by_top_y_index
+)
+{
+    if (!empty_space || empty_space.get_y() <= 0)
+    {
+        return []
+    }
+
+    const space_bottom = empty_space.get_y()
+    const candidate_items = resolve_candidate_items(
+        container,
+        supporters_by_top_y_index,
+        space_bottom
+    )
+    const orientation_by_group_id = build_tie_ratio_orientation_by_group_id(
+        container.get_allocated_items?.() ?? []
+    )
+    const orientations = new Set()
+    for (const item of candidate_items)
+    {
+        if (footprint_overlap_on_space(item, empty_space) <= 0)
+        {
+            continue
+        }
+        const orientation = tie_ratio_orientation_from_item(item, orientation_by_group_id)
+        if (orientation === '3_2' || orientation === '2_3')
+        {
+            orientations.add(orientation)
+        }
+    }
+    return [...orientations]
+}
+
+function resolve_candidate_items(container, supporters_by_top_y_index, space_bottom)
+{
+    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 =>
+        math.eq(item.get_y() + item.get_height(), space_bottom)
+    )
+}
+
+module.exports = {
+    collect_tie_ratio_orientations_below_footprint
+}

package/src/Allocation_Optimization/tie_ratio/filter_blocks_by_orientation.js

@@ -0,0 +1,17 @@
+/**
+ * Keeps non-tie-ratio blocks and tie-ratio blocks matching the required orientation.
+ * @param {object[]} block_list
+ * @param {'3_2'|'2_3'} required_orientation
+ * @returns {object[]}
+ */
+module.exports = function filter_blocks_by_orientation(block_list, required_orientation)
+{
+    return block_list.filter(block =>
+    {
+        if (!block.is_tie_ratio_block())
+        {
+            return true
+        }
+        return block.get_tie_ratio_orientation() === required_orientation
+    })
+}

package/src/Allocation_Optimization/tie_ratio/find_orientation_below_space.js

@@ -0,0 +1,77 @@
+const math = require('@jetta/number-compare')
+const { supporters_at_top_y } = require('./supporters_by_top_y_index')
+const { footprint_overlap_on_space } = require('./loose_on_block/tie_ratio_footprint_overlap')
+const {
+    build_tie_ratio_orientation_by_group_id,
+    tie_ratio_orientation_from_item
+} = require('./tie_ratio_orientation_from_group')
+
+/**
+ * Finds tie-ratio orientation of a compound block directly under an empty space footprint.
+ * @param {object} container - Container with allocated items.
+ * @param {object|undefined} empty_space - Candidate empty space (may be undefined during pre-selection).
+ * @param {import('./supporters_by_top_y_index').Supporters_By_Top_Y_Index|undefined} supporters_by_top_y_index
+ * @returns {'3_2'|'2_3'|undefined}
+ */
+module.exports = function find_orientation_below_space(
+    container,
+    empty_space,
+    supporters_by_top_y_index
+)
+{
+    if (!empty_space || empty_space.get_y() <= 0)
+    {
+        return undefined
+    }
+
+    const allocated_items = container.get_allocated_items?.() ?? []
+    const orientation_by_group_id = build_tie_ratio_orientation_by_group_id(allocated_items)
+    const space_bottom = empty_space.get_y()
+    const candidate_items = resolve_candidate_items(
+        container,
+        supporters_by_top_y_index,
+        space_bottom
+    )
+    return orientation_from_candidates(
+        candidate_items,
+        empty_space,
+        orientation_by_group_id
+    )
+}
+
+function resolve_candidate_items(container, supporters_by_top_y_index, space_bottom)
+{
+    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 =>
+        math.eq(item.get_y() + item.get_height(), space_bottom)
+    )
+}
+
+function orientation_from_candidates(candidate_items, empty_space, orientation_by_group_id)
+{
+    let best_orientation = undefined
+    let best_footprint_overlap = -1
+    for (const item of candidate_items)
+    {
+        const footprint_overlap = footprint_overlap_on_space(item, empty_space)
+        if (footprint_overlap <= 0)
+        {
+            continue
+        }
+        const orientation = tie_ratio_orientation_from_item(item, orientation_by_group_id)
+        if (orientation === undefined)
+        {
+            continue
+        }
+        if (footprint_overlap <= best_footprint_overlap)
+        {
+            continue
+        }
+        best_footprint_overlap = footprint_overlap
+        best_orientation = orientation
+    }
+    return best_orientation
+}

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

@@ -0,0 +1,31 @@
+/**
+ * True when two axis-aligned allocated items occupy the same volume.
+ * @param {object} left
+ * @param {object} right
+ * @returns {boolean}
+ */
+function allocated_items_penetrate(left, right)
+{
+    const overlap_x = Math.min(left.get_x() + left.get_width(), right.get_x() + right.get_width())
+        - Math.max(left.get_x(), right.get_x())
+    const overlap_y = Math.min(left.get_y() + left.get_height(), right.get_y() + right.get_height())
+        - Math.max(left.get_y(), right.get_y())
+    const overlap_z = Math.min(left.get_z() + left.get_length(), right.get_z() + right.get_length())
+        - Math.max(left.get_z(), right.get_z())
+    return overlap_x > 1e-6 && overlap_y > 1e-6 && overlap_z > 1e-6
+}
+
+/**
+ * True when the candidate penetrates any other occupant.
+ * @param {object} candidate
+ * @param {object[]} occupants
+ * @returns {boolean}
+ */
+function allocated_item_penetrates_any(candidate, occupants)
+{
+    return occupants.some(occupant =>
+        occupant !== candidate && allocated_items_penetrate(candidate, occupant)
+    )
+}
+
+module.exports = allocated_item_penetrates_any

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

@@ -0,0 +1,94 @@
+const Cargo_Profile = require('../../../models/Cargo_Profile')
+const find_tie_ratio_supporter_cluster = require('./find_tie_ratio_supporter_cluster')
+const resolve_loose_placement_position = require('./resolve_loose_placement_position')
+const container_with_pending_wall_items = require('./container_with_pending_wall_items')
+const {
+    resolve_without_tie_ratio_cluster,
+    finalize_placement_coords
+} = require('./resolve_without_tie_ratio_cluster')
+
+/**
+ * Realigns a placed loose item to a tie-ratio slot when valid.
+ * @param {object} allocated_item
+ * @param {object} container
+ * @param {object} empty_space
+ * @param {object} slot_state
+ * @param {object|undefined} supporters_by_top_y_index
+ * @param {object[]|undefined} pending_wall_allocated_items
+ * @returns {object|undefined}
+ */
+function apply_loose_placement_to_allocated_item(
+    allocated_item,
+    container,
+    empty_space,
+    slot_state,
+    supporters_by_top_y_index,
+    pending_wall_allocated_items
+)
+{
+    const allocation_item = allocated_item.get_stacking_source_item()
+    const container_view = container_with_pending_wall_items(
+        container,
+        pending_wall_allocated_items
+    )
+    const placement_options = {
+        item_width: allocated_item.get_width(),
+        item_length: allocated_item.get_length(),
+        item_height: allocated_item.get_height(),
+        require_same_area: Cargo_Profile.stack_loose_on_tie_ratio_blocks(),
+        loose_origin_x: allocated_item.get_x(),
+        loose_origin_z: allocated_item.get_z()
+    }
+    const cluster = find_tie_ratio_supporter_cluster(
+        container_view,
+        empty_space,
+        supporters_by_top_y_index,
+        allocated_item.get_y(),
+        placement_options
+    )
+    if (cluster === undefined)
+    {
+        return resolve_without_tie_ratio_cluster(
+            allocated_item,
+            container,
+            container_view,
+            empty_space,
+            slot_state,
+            placement_options,
+            allocation_item
+        )
+    }
+    const placement = resolve_loose_placement_position(
+        container_view,
+        empty_space,
+        slot_state,
+        supporters_by_top_y_index,
+        placement_options,
+        allocated_item.get_y(),
+        cluster
+    )
+    if (placement !== undefined)
+    {
+        const tied_item = finalize_placement_coords(
+            container,
+            container_view,
+            allocation_item,
+            placement
+        )
+        if (tied_item !== undefined)
+        {
+            return tied_item
+        }
+    }
+    return resolve_without_tie_ratio_cluster(
+        allocated_item,
+        container,
+        container_view,
+        empty_space,
+        slot_state,
+        placement_options,
+        allocation_item
+    )
+}
+
+module.exports = apply_loose_placement_to_allocated_item

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

@@ -0,0 +1,16 @@
+/**
+ * Returns overlap length on a single axis between two ranges.
+ * @param {number} start_a
+ * @param {number} end_a
+ * @param {number} start_b
+ * @param {number} end_b
+ * @returns {number}
+ */
+function axis_overlap_length(start_a, end_a, start_b, end_b)
+{
+    const overlap_start = Math.max(start_a, start_b)
+    const overlap_end = Math.min(end_a, end_b)
+    return Math.max(0, overlap_end - overlap_start)
+}
+
+module.exports = axis_overlap_length

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

@@ -0,0 +1,18 @@
+/**
+ * Computes the local origin (min x, min z) of a supporter cluster.
+ * @param {object[]} cluster_items
+ * @returns {{ min_x: number, min_z: number }}
+ */
+function block_local_origin(cluster_items)
+{
+    let min_x = Infinity
+    let min_z = Infinity
+    for (const item of cluster_items)
+    {
+        min_x = Math.min(min_x, item.get_x())
+        min_z = Math.min(min_z, item.get_z())
+    }
+    return { min_x, min_z }
+}
+
+module.exports = block_local_origin

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

@@ -0,0 +1,39 @@
+const math = require('@jetta/number-compare')
+
+/**
+ * @param {object|undefined} container
+ * @param {number} origin_x
+ * @param {number} origin_y
+ * @param {number} origin_z
+ * @param {number} item_width
+ * @param {number} item_height
+ * @param {number} item_length
+ * @returns {boolean}
+ */
+function box_fits_inside_container(
+    container,
+    origin_x,
+    origin_y,
+    origin_z,
+    item_width,
+    item_height,
+    item_length
+)
+{
+    if (container === undefined || typeof container.get_width !== 'function')
+    {
+        return true
+    }
+    if (math.lt(origin_x, 0) || math.lt(origin_y, 0) || math.lt(origin_z, 0))
+    {
+        return false
+    }
+    const end_x = origin_x + item_width
+    const end_y = origin_y + item_height
+    const end_z = origin_z + item_length
+    return math.le(end_x, container.get_width())
+        && math.le(end_y, container.get_height())
+        && math.le(end_z, container.get_length())
+}
+
+module.exports = box_fits_inside_container

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

@@ -0,0 +1,18 @@
+const Allocated_Item = require('../../../models/Allocated_Item')
+
+/**
+ * @param {object} allocation_item
+ * @param {{ x: number, y: number, z: number }} placement
+ * @returns {object}
+ */
+function build_allocated_item_at_placement(allocation_item, placement)
+{
+    return new Allocated_Item(
+        allocation_item,
+        placement.x,
+        placement.y,
+        placement.z
+    )
+}
+
+module.exports = build_allocated_item_at_placement