🌟 Perlita Falling 🌟

Simulador de Acumulación de Partículas de Perlita

Un simulador de física de partículas desarrollado en Python que simula el comportamiento de caida de partículas de perlita expandida en un contenedor para su posterior empaquetado. Si se habilita el nivel de llenado, el sistema abre las compuertas de drenaje automaticamente cuando el 95% del volumen por debajo del nivel es alcanzado.

video.mp4

📋 Descripción

Este simulador de partículas simula el comportamiento físico de materiales granulares como la perlita expandida. Las partículas caen por gravedad, se acumulan y responden a las interacciones físicas de manera natural. Incluye un sistema de nivel automático con drenaje cuando se alcanza cierta capacidad.

Esta simulacion se hace para poder avanzar en el desarrollo y prototipado de un proyecto de semi automatizacion industrial de una linea de produccion de perlita expandida para su posterior empaquetado. El campo de juego es una representacion de un visor de inspeccion de una tolva de llenado de la linea de produccion, mediante el cual se puede saber el nivel de llenado de la misma. A traves de una camara, se puede detectar (con procesamiento de imagenes y/o opencv) el nivel de llenado de la tolva y enviar una señal al sistema para que se activen electrovalvulas de apertura y se vacie el contenido de la camara.

🎯 Características Principales

• Simulación de Física: Gravedad, colisiones y acumulación natural
• Múltiples tamaños de Partículas: Partículas de perlita de distintos tamaños
• Sistema de Nivel Automático: Drenaje automático cuando se alcanza el nivel configurado
• Aparición Configurable: Control de velocidad, área y tamaño de clusters de aparicion de partículas
• Interfaz Interactiva: Dibuja con mouse, cambia modos y configura parámetros
• Redimensionamiento Dinámico: Ajusta el tamaño visual de las partículas en tiempo real
• Arquitectura Modular: Código bien organizado y documentado

🚀 Instalación

Requisitos del Sistema

• Python 3.8 o superior

Dependencias

# Instalar pygame (única dependencia externa)
pip install pygame

Instalación Paso a Paso

1. Clonar el repositorio:

   git clone https://github.com/tu-usuario/simulador-perlita.git
   cd simulador-perlita

2. Instalar dependencias:

   pip install pygame

3. Ejecutar el simulador:

   cd "Perlita falling"
   python main.py

🎮 Controles y Uso

Controles de Movimiento y Configuración

Tecla	Función
↑ ↓	Aumentar/Disminuir velocidad de aparición
← →	Encoger/Ampliar área de caída
Re Pág / Av Pág	Más/Menos partículas por cluster
1-9	Cambiar tamaño visual de píxeles

Modos de Dibujo

Tecla	Modo
P	Modo Perlita
R	Modo Roca
E	Modo Borrador

Controles del Sistema

Tecla	Función
A	Activar/Desactivar aparición automática
O	Pausar/Reanudar simulación
L	Activar línea de nivel
Inicio/Fin	Subir/Bajar línea de nivel
Espacio	Limpiar todo el campo
ESC	Volver al menú

Controles de Mouse

• Click Izquierdo: Dibujar partículas del tipo seleccionado
• Arrastrar: Dibujar continuamente mientras se mueve

📁 Estructura del Proyecto

perlita falling v3/
├── main.py                    # 🎮 Punto de entrada principal del juego
├── simulacion.py              # 🎯 Coordinador principal de todos los sistemas
├── particulas.py              # ⚪ Definición de tipos de partículas (perlita, roca)
├── grillas.py                 # 🔲 Sistema de grilla y manejo de la matriz de simulación
├── sistema/                 # ⚙️ Sistemas especializados del juego
│   ├── __init__.py            # Inicializador del paquete de sistemas
│   ├── mensajes.py            # 💬 Sistema de mensajes temporales en pantalla
│   ├── aparicion.py           # 🌟 Control de generación automática de partículas
│   ├── nivel.py               # 📏 Sistema de nivel y drenaje automático
│   ├── input.py               # 🎮 Manejo de entrada (teclado y mouse)
│   └── fisicas.py             # 🔬 Motor de física para movimiento de partículas
├── ui/                      # 🎨 Interfaz de usuario y renderizado
│   ├── __init__.py            # Inicializador del paquete de UI
│   ├── render_juego.py        # 🎮 Renderizador de la pantalla de juego
│   ├── render_menu.py         # 📋 Renderizador de menús y pantalla de inicio
│   └── hud.py                 # 📊 Elementos adicionales de interfaz
├── core/                    # 🏗️ Componentes fundamentales
│   ├── __init__.py            # Inicializador del paquete core
│   ├── constantes.py          # 📋 Todas las constantes de configuración
│   ├── estado_juego.py        # 🔄 Manejo de estados del juego
│   └── utilidades.py          # 🛠️ Funciones de utilidad comunes
└── README.md                  # 📖 Este archivo de documentación

🔧 Descripción Detallada de Archivos

Archivos Principales

• main.py: Punto de entrada que inicializa pygame, maneja la ventana y coordina los estados del juego (splash, menú, simulación).

• simulacion.py: Clase principal que coordina todos los sistemas. Integra física, aparición, nivel, input y mensajes en un solo lugar.

• particulas.py: Define las clases ParticulaPerlita y ParticulaRoca con sus comportamientos físicos específicos.

• grillas.py: Implementa el sistema de grilla que divide el espacio en celdas para optimizar las colisiones y el renderizado.

Sistema de Subsistemas

• sistema/mensajes.py: Maneja los mensajes temporales que aparecen en pantalla para informar cambios al usuario.

• sistema/aparicion.py: Controla la generación automática de partículas: velocidad, posición, clusters y área de aparición.

• sistema/nivel.py: Implementa el sistema de drenaje automático cuando las partículas alcanzan un nivel determinado.

• sistema/input.py: Procesa toda la entrada del usuario (teclado y mouse) y la traduce a acciones del juego.

• sistema/fisicas.py: Motor de física que actualiza las posiciones de las partículas según gravedad y colisiones.

Interfaz de Usuario

• ui/render_juego.py: Renderiza la pantalla principal del juego incluyendo el área de simulación, mensajes e instrucciones.

• ui/render_menu.py: Maneja el renderizado del splash screen con logo y el menú principal.

• ui/hud.py: Elementos adicionales como indicadores de modo e información de debug.

Componentes Core

• core/constantes.py: Centraliza todas las constantes de configuración para fácil modificación.

• core/estado_juego.py: Maneja las transiciones entre estados (splash → menú → juego).

• core/utilidades.py: Funciones de utilidad como interpolación, cálculo de distancias, temporizadores, etc.

⚙️ Configuración

Modificar Parámetros de Simulación

Edita core/constantes.py para ajustar:

# Velocidad de aparición
VELOCIDAD_APARICION_POR_DEFECTO = 1.0
VELOCIDAD_APARICION_MAXIMA = 10.0

# Área de simulación
ANCHO_AREA_JUEGO = 200
ALTO_AREA_JUEGO = 600

# Sistema de drenaje
TIEMPO_DRENAJE_SEGUNDOS = 2.0

Personalizar Colores

# En core/constantes.py
COLOR_PERLITA = (240, 240, 235)
COLOR_ROCA = (100, 100, 100)
COLOR_BORDE = (0, 255, 0)

🔬 Aspectos Técnicos

Algoritmo de Física

1. Actualización por Frames: Cada frame actualiza todas las partículas desde abajo hacia arriba
2. Detección de Colisiones: Sistema de grilla optimizado para colisiones eficientes
3. Gravedad Simulada: Las partículas intentan caer, con colisiones laterales si hay obstáculos
4. Prevención de Sesgos: Alternancia de dirección de procesamiento para evitar patrones artificiales

Sistema de Aparición Inteligente

• Velocidades Fraccionarias: Permite velocidades como 0.5 (50% probabilidad por frame)
• Clusters Configurables: Genera grupos de partículas para simular comportamiento realista
• Área Variable: Desde aparición puntual hasta cobertura completa del ancho

Optimizaciones de Rendimiento

• Grilla Espacial: División del espacio para colisiones O(1) en lugar de O(n²)
• Procesamiento Selectivo: Solo actualiza partículas que pueden moverse
• Renderizado Optimizado: Superficie temporal para reducir operaciones de dibujo

🐛 Solución de Problemas

El juego no inicia

1. Verificar que Python 3.8+ esté instalado:

   python --version

2. Verificar que pygame esté instalado:

   python -c "import pygame; print('Pygame OK')"

Rendimiento lento

1. Reducir el tamaño del área de juego en constantes.py
2. Disminuir la velocidad de aparición
3. Usar tamaños de celda más grandes (teclas 7-9)

Problemas de ventana

• El juego soporta redimensionamiento dinámico
• Usar ESC para volver al menú si hay problemas
• Reiniciar con Espacio si la simulación se vuelve muy densa

🤝 Como contribuir

1. Fork al proyecto
2. Crea una rama para tu feature (git checkout -b feature/nueva-caracteristica)
3. Commit a tus cambios (git commit -am 'Agregar nueva característica')
4. Push a la rama (git push origin feature/nueva-caracteristica)
5. Abre un Pull Request

Guías de Contribución

• Mantener el código en español en lo posible
• Documentar todas las funciones
• Seguir la estructura modular existente
• Agregar tests para nuevas características
• Usar nombres descriptivos para variables y funciones

📜 Licencia

Este proyecto está bajo la Licencia MIT. Ver LICENSE para más detalles.

Créditos

Partes del codigo (la simulacion de fisica en particular) estan inspiradas en el siguiente proyecto sin licencia:

• Python-Falling-Sand-with-pygame
  Autor: Programming With Nick

🏢 Desarrollado para

TUCUMORDOR - Automatizacion Industrial en Tucumán, Argentina

---

⭐ ¡Dale una estrella si te gusta el proyecto! ⭐