add readme.md
This commit is contained in:
VALLONGOL
parent
139226d7a3
commit
7f99462317
165
README.md
Normal file
165
README.md
Normal file
@ -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.
|
||||||
Loading…
Reference in New Issue
Block a user