diff --git a/README.md b/README.md new file mode 100644 index 0000000..299b1bd --- /dev/null +++ b/README.md @@ -0,0 +1,165 @@ +# 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): + +```bash +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:** + +```bash +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): + +```bash +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:** + +```bash +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.