PNG to ICO Converter

This Python script, create_icon_file.py, converts PNG images into ICO (Windows icon) files. It offers options for background removal, custom icon sizes, and can be run either as a standalone graphical application or as a command-line tool for integration into automated workflows.

---

English

Features

• PNG to ICO Conversion: Core functionality to create multi-resolution ICO files from a single PNG source.
• Background Removal: Option to make white or near-white pixels in the source PNG transparent in the resulting ICO.
• Custom Sizes: Specify a comma-separated list of desired icon sizes (e.g., "16,32,48,64,128,256").
• Standalone GUI Mode:
  • User-friendly interface built with Tkinter/ttk.
  • Preview of the selected PNG image.
  • Interactive selection of input PNG and output ICO file paths.
  • Checkbox to enable/disable background removal.
  • Input field for custom icon sizes.
  • Scrollable preview area showing how the icon will look at each generated size.
• Managed CLI Mode:
  • Designed for integration with a "ProjectUtility" or similar automation systems.
  • Uses the tool_utils library (expected to be in a ToolUtils directory, typically a sibling to the script's parent directory) for argument parsing, communication (progress, status, results), and configuration loading.
  • Accepts parameters via command-line arguments.
  • Configuration for CLI parameters is typically managed via a tool_config_params.json file.

Requirements

• Python 3.x
• Pillow (PIL Fork): pip install Pillow
• Tkinter (usually included with standard Python installations)
• (For Managed CLI Mode) tool_utils module: This module is expected to be located in a directory named ToolUtils. The script attempts to find it in a directory that is a sibling to the script's parent directory (e.g., if the script is in Project/Tool/create_icon_file.py, ToolUtils should be in Project/ToolUtils/).

Usage

1. Standalone GUI Mode

To run the script with its graphical interface (e.g., for interactive, one-off conversions):

python create_icon_file.py

No command-line arguments are needed. The application window will open, allowing you to:

1. Click "Select PNG Image" to choose your source file.
2. Optionally, uncheck "Remove white/near-white background" if you want to keep the background.
3. Modify the "Sizes (csv)" field if you need different icon dimensions (default is "16,32,48,64,128,256").
4. Click "Convert and Save ICO" and choose a location and name for your output .ico file.
5. Previews of the generated sizes will appear in the lower panel after successful conversion.

(Placeholder for a screenshot of the GUI)

2. Managed CLI Mode

This mode is intended for use within an automated system that invokes the script with arguments. The script detects this mode if any command-line arguments are provided.

Example Command:

python create_icon_file.py --input-png /path/to/source.png --output-ico /path/to/output.ico --sizes "16,32,48,256" --remove-bg

Command-line Arguments (as typically defined in tool_config_params.json):

• --input-png: (Required) Path to the source PNG file.
• --output-ico: (Required) Path where the generated ICO file will be saved.
• --sizes: (Optional) Comma-separated string of desired icon sizes (e.g., "16,32,64"). Defaults to "16,32,48,64,128,256" if not provided.
• --remove-bg: (Optional flag) If present, attempts to remove white/near-white backgrounds.

The exact argument names and whether they are required or optional are defined in the tool_config_params.json file, which is loaded by the tool_utils.parse_arguments function.

tool_utils Integration

When run in managed mode, the script relies on a tool_utils package for several functions:

• parse_arguments: Parses command-line arguments based on a configuration file.
• load_tool_config: Loads the tool's parameter definitions.
• send_progress, send_status, send_log, send_result: Communicate tool execution state and results back to the calling utility.
• print_error, exit_success: Standardized error reporting and exit.

If tool_utils cannot be imported, the script will print an error and exit with code 4, as it's essential for managed mode operation.

---

Italiano

Funzionalità

• Conversione da PNG a ICO: Funzionalità principale per creare file ICO multi-risoluzione da una singola immagine PNG sorgente.
• Rimozione Sfondo: Opzione per rendere trasparenti i pixel bianchi o quasi bianchi nell'immagine PNG sorgente nel file ICO risultante.
• Dimensioni Personalizzate: Specifica un elenco separato da virgole delle dimensioni desiderate per le icone (es. "16,32,48,64,128,256").
• Modalità GUI Autonoma:
  • Interfaccia utente intuitiva costruita con Tkinter/ttk.
  • Anteprima dell'immagine PNG selezionata.
  • Selezione interattiva dei percorsi del file PNG di input e del file ICO di output.
  • Casella di controllo per abilitare/disabilitare la rimozione dello sfondo.
  • Campo di input per le dimensioni personalizzate delle icone.
  • Area di anteprima scorrevole che mostra come apparirà l'icona per ciascuna dimensione generata.
• Modalità CLI Gestita:
  • Progettata per l'integrazione con una "ProjectUtility" o sistemi di automazione simili.
  • Utilizza la libreria tool_utils (che ci si aspetta si trovi in una directory ToolUtils, tipicamente sorella della directory genitore dello script) per il parsing degli argomenti, la comunicazione (avanzamento, stato, risultati) e il caricamento della configurazione.
  • Accetta parametri tramite argomenti da riga di comando.
  • La configurazione per i parametri CLI è tipicamente gestita tramite un file tool_config_params.json.

Requisiti

• Python 3.x
• Pillow (Fork di PIL): pip install Pillow
• Tkinter (solitamente incluso nelle installazioni standard di Python)
• (Per la Modalità CLI Gestita) Modulo tool_utils: Ci si aspetta che questo modulo si trovi in una directory chiamata ToolUtils. Lo script tenta di trovarla in una directory che è sorella della directory genitore dello script (ad esempio, se lo script è in Progetto/Strumento/create_icon_file.py, ToolUtils dovrebbe essere in Progetto/ToolUtils/).

Utilizzo

1. Modalità GUI Autonoma

Per eseguire lo script con la sua interfaccia grafica (ad esempio, per conversioni interattive e occasionali):

python create_icon_file.py

Non sono necessari argomenti da riga di comando. Si aprirà la finestra dell'applicazione, consentendo di:

1. Cliccare su "Select PNG Image" per scegliere il file sorgente.
2. Opzionalmente, deselezionare "Remove white/near-white background" se si desidera mantenere lo sfondo.
3. Modificare il campo "Sizes (csv)" se si necessita di dimensioni diverse per le icone (il predefinito è "16,32,48,64,128,256").
4. Cliccare su "Convert and Save ICO" e scegliere una posizione e un nome per il file .ico di output.
5. Le anteprime delle dimensioni generate appariranno nel pannello inferiore dopo una conversione riuscita.

(Spazio per uno screenshot della GUI)

2. Modalità CLI Gestita

Questa modalità è pensata per l'uso all'interno di un sistema automatizzato che invoca lo script con argomenti. Lo script rileva questa modalità se vengono forniti argomenti da riga di comando.

Comando Esempio:

python create_icon_file.py --input-png /percorso/immagine.png --output-ico /percorso/icona.ico --sizes "16,32,48,256" --remove-bg

Argomenti da Riga di Comando (come tipicamente definiti in tool_config_params.json):

• --input-png: (Obbligatorio) Percorso del file PNG sorgente.
• --output-ico: (Obbligatorio) Percorso dove verrà salvato il file ICO generato.
• --sizes: (Opzionale) Stringa di dimensioni delle icone separate da virgola (es. "16,32,64"). Predefinito a "16,32,48,64,128,256" se non fornito.
• --remove-bg: (Flag opzionale) Se presente, tenta di rimuovere gli sfondi bianchi/quasi bianchi.

I nomi esatti degli argomenti e se sono obbligatori o opzionali sono definiti nel file tool_config_params.json, che viene caricato dalla funzione tool_utils.parse_arguments.

Integrazione con tool_utils

Quando eseguito in modalità gestita, lo script si affida a un pacchetto tool_utils per diverse funzioni:

• parse_arguments: Esegue il parsing degli argomenti da riga di comando basandosi su un file di configurazione.
• load_tool_config: Carica le definizioni dei parametri dello strumento.
• send_progress, send_status, send_log, send_result: Comunicano lo stato di esecuzione dello strumento e i risultati all'utility chiamante.
• print_error, exit_success: Segnalazione errori e uscita standardizzate.

Se tool_utils non può essere importato, lo script stamperà un errore e uscirà con codice 4, poiché è essenziale per il funzionamento in modalità gestita.

---

License

Specify your license here (e.g., MIT License, GPLv3, etc.). If no license is specified, it's typically considered All Rights Reserved.