Cargo Load Optimisation by CLOA, powered by Gemini 3 Pro

CLOA (Container Load Optimisation App) is a 3D visualisation tool, designed to maximise the efficiency of cargo van loading. It simulates the placement of various standard parcel types into a fixed-size cargo van, generates real-time utilisation statistics and uses the Gemini API to provide AI optimisation insights.

Tip

This app was built as a part of Google DeepMind - Vibe Code with Gemini 3 Pro in AI Studio competition on Kaggle.

📑 Table of Contents

• Optimisation Challenge
• Solution Logic and Architecture
• Run CLOA App Locally
• Run Docker Container
• Demos

Optimisation Challenge

This app is designed to assist with the load optimisation challenge, which requires efficient arrangement of a given set of defined items within a larger container. It's currently tuned for a standard delivery vehicle:

• Container Dimensions (L x W x H): 3.0 m x 1.8 m x 1.9 m.
• Total Volume: 10.26 m³.

The cargo load optimisation process assumes the use of the following parcel types:

Type	Dimensions (L x W x H)	Volume	Colour Code
Small	0.30m x 0.20m x 0.15m	0.009 m³	Green
Medium	0.50m x 0.40m x 0.30m	0.060 m³	Blue
Large	0.75m x 0.50m x 0.60m	0.225 m³	Red

Note

The underlying parcel-packing logic can be extended to address complex logistics and manufacturing challenges outside of cargo-van loading:

• Diverse Container Types: The app can be adapted to optimise loading for various transport vessels, such as shipping containers, rail wagons or aircraft cargo, by updating the CONTAINER dimensions defined within types.ts.
• Internal Product Packaging: The packing principles apply at a micro-level. For instance, the same solution logic could be used to optimise the arrangement of internal components (e.g., circuit boards, batteries) within a final product's casing, helping to minimise the product's size or reduce wasted space.
• Advanced Constraints: The logic can be extended to include complex logistical constraints, such as optimising for weight distribution (centre of gravity) or fragility rules (prohibiting the stacking of delicate items).

Solution Logic and Architecture

The app is built using React front-end and provides an interactive 3D visualisation using Three.js library. There are two main building blocks: Cargo Packing Simulation and AI Optimisation Assistant.

Cargo Packing Simulation

The packing calculation is managed by the packContainer service, which accepts user input from the ControlPanel.tsx component:

• Input: Users specify the quantity for the three standard parcel types.
• Logic: The heuristic solver calculates the optimal 3D coordinates for each parcel, allowing for full rotation to achieve the highest possible packing density.
• Visualisation: The result is displayed in a rotatable 3D model, where each parcel is clearly colour-coded by type (Small/Green, Medium/Blue, Large/Red).

AI Optimisation Assistant

AI-based feedback and suggestions can be generated, leveraging the Gemini API:

• The getOptimizationInsights service is triggered after the simulation. It passes the raw packing data (placed and unplaced items, utilisation) to the Gemini model.
• Gemini analyses the loading statistics and returns actionable recommendations (e.g., "Consider reducing the number of Large parcels by 2, as they are causing significant gaps")
• The Gemini API Key is loaded from the .env.local file and injected via vite.config.ts.

Run CLOA App Locally

The app requires Node.js runtime environment for its setup and execution. Please, follow these 3 steps to launch the CLOA app locally.

1. Install dependencies:

npm install

2. Set the GEMINI_API_KEY: Update the GEMINI_API_KEY in .env.local with your personal Gemini API key.

3. Run the application:

npm run dev

Important

The app's UI will be accessible at http://localhost:3000.

Run Docker Container

For a consistent and portable environment, the repo comes with a pre-packaged Docker image companion. You can run it with the following Docker CLI command:

docker run -d -p 3000:80 --env GEMINI_API_KEY="YOUR_API_KEY" ghcr.io/lazauk/cloa-app:latest

Important

The programme will be accessible in your browser at http://localhost:3000. The --env flag is mandatory to pass the required GEMINI_API_KEY environment variable into the running container.

Demos

To see the CLOA app in action:

• Published App Link: Google AI Studio app
• Video Demonstration: YouTube Link