=== JYP Image Transparency Converter — transparency & resize tool ===
Contributors: jypdevelopment
Requires at least: 6.0
Requires PHP: 7.4
Tested up to: 7.1
Stable tag: 1.3.0
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html
Donate link: https://jyp-plugins.tech/donate/
Documentation: https://jyp-plugins.tech/jyp-image-transparency-converter/

Removes a solid background from an uploaded image, resizes it if needed, and saves the result as PNG or WebP.

== Description ==

If you work with website content, you may often find yourself using different tools to remove backgrounds, resize images, and prepare them in the same format before uploading them to WordPress. This can become repetitive, especially when you need to prepare a large number of images in the same way.

**JYP Image Transparency Converter** is designed to make this part of the job easier. Select the images you want to prepare, set the conversion options once, and let the plugin process them in the same way. This helps you keep a consistent look and image format across a whole set of images without having to process each one manually.

The plugin adds **Tools > JYP Image Transparency Converter** to the WordPress admin area. It removes a solid background from your images and can resize them at the same time.

The background colour is taken from one of the image's corners. You can adjust the tolerance to control how much of the similar colour is made transparent.

**Author:** JYP - Just Your Plugin
**Author URI:** https://jyp-plugins.tech/

You can select any number of individual images, including images from different locations. Selected images are added to a thumbnail grid and uploaded only when you start the conversion.

You can also select a local directory using the standard browser folder picker. In directory mode, the plugin can process image files from the selected directory and its subdirectories. Converted files are saved in the WordPress uploads directory with the `-t` suffix.

The **Convert to PNG** and **Convert to WebP** buttons process images asynchronously, without reloading the admin page. The result or any processing errors are shown below the buttons.

Each successfully converted image is saved to the WordPress uploads directory and registered in the **Media Library** using the standard WordPress attachment API. This means the converted image becomes a normal WordPress media item, just as if you had uploaded the file through the Media Library yourself. WordPress then generates the configured intermediate image sizes and stores the metadata in the same way as it does for a normally uploaded image.

== REST API ==

The REST endpoint is `POST /wp-json/jypitc/v1/convert`. Authenticate with a WordPress Application Password using HTTP Basic Authentication.

You can send one or more images as `files[]` multipart fields, or pass `directory` as a relative directory inside the WordPress uploads directory.

Supported parameters include `format` (`png` or `webp`), `convert_size` (`1`), `width`, `height`, `preserve_proportions` (`1`), `output_subdirectory`, `include_subdirectories` (`1`), and `preserve_structure` (`1`). When `convert_size` is enabled, both `width` and `height` are required.

Example:

    curl -u "admin:APPLICATION_PASSWORD" -F "files[]=@photo.jpg" -F "format=png" -F "convert_size=1" -F "width=1200" -F "height=1200" -F "preserve_proportions=1" https://example.com/wp-json/jypitc/v1/convert

== WP-CLI ==

The command is `wp jyp-image-transparency-converter`. Use `--files` with a comma-separated list of local files or `--directory` with a local directory.

It accepts the same conversion options as the REST endpoint:

    wp jyp-image-transparency-converter --files=photo.jpg,logo.png --format=webp --convert_size=1 --width=1200 --height=1200 --preserve_proportions=1
    wp jyp-image-transparency-converter --directory=./images --include_subdirectories=1 --preserve_structure=1

WP-CLI uses the WordPress user configured for the command, for example with `--user`. Application Passwords are used to authenticate the REST API over HTTP.

== Developer hooks ==

The plugin provides standard WordPress actions and filters for developers who need to customise the conversion process:

* `jypitc_background_tolerance` — filter the background colour tolerance.
* `jypitc_transparent_pixel_source` — filter the reference pixel corner.
* `jypitc_output_postfix` — filter the generated filename postfix.
* `jypitc_existing_file_behavior` — filter `replace` or `unique` conflict handling.
* `jypitc_external_conversion_options` — filter REST/WP-CLI conversion options.
* `jypitc_conversion_items` — filter the source item list before conversion.
* `jypitc_before_conversion` and `jypitc_after_conversion` — actions around external conversion.
* `jypitc_conversion_result` — filter the external conversion result.
* `jypitc_image_processor` — choose `imagick` or `gd`.
* `jypitc_resize_settings` — filter resize settings.
* `jypitc_pixel_coordinates` — filter the sampled pixel coordinates.
* `jypitc_upload_destination` — filter the destination path and URL.
* `jypitc_output_filename` — filter the generated filename.
* `jypitc_attachment_args` — filter attachment post data before insertion.
* `jypitc_attachment_registered` — action after attachment metadata is saved.
* `jypitc_settings_saved` and `jypitc_settings_save_response` — actions and response filtering for settings.
* `jypitc_rest_permission_callback` and `jypitc_rest_routes_registered` — customise REST access and route registration.
* `jypitc_rest_conversion_result` and `jypitc_cli_conversion_result` — filter API and WP-CLI results.
* `jypitc_ajax_conversion_result` — filter AJAX conversion results.

The **Conversion progress** panel lists every selected image with a thumbnail and its original relative path. Files are sent and processed one at a time, so each item is updated as the conversion progresses.

Successful conversions show a green check mark and a link to the generated file. If a conversion fails, a red cross and the error message are shown instead.

Next to **Uploads subdirectory**, the optional **Convert size** setting lets you set the image width and height in pixels.

**Preserve proportions** fits each result within the specified dimensions without exceeding either value. When it is disabled, the result uses the exact width and height you specify.

On the **Make Transparent** tab, the default **Uploads subdirectory** is the current WordPress date directory (`YYYY/MM`), matching the standard WordPress media upload behaviour. Other existing subdirectories inside uploads can also be selected.

For directory processing, **Including subdirectories** is enabled by default. **Preserve directory structure** recreates the selected folder's relative subdirectories under the chosen uploads directory and is available only when subdirectory scanning is enabled.

Imagick is used when available, with GD as a fallback. JPEG files can be used as input because the plugin converts them to PNG or WebP, which support transparency.

The **Settings** tab contains the background tolerance, reference corner pixel, output postfix, and existing file behaviour options.

The reference pixel can be selected from the top-left, top-right, bottom-left, or bottom-right corner. When **Add unique identifier** is selected, a random seven-character alphanumeric identifier is added before the extension.

Settings are saved asynchronously with the **Save settings** button and stored in the WordPress database.

== Installation ==

1. Copy the `jyp-image-transparency-converter` directory to `wp-content/plugins/`.
2. Activate the plugin in **Plugins**.
3. Open **Tools > JYP Image Transparency Converter**.
4. Upload an image and select PNG or WebP.
