diff --git a/README.md b/README.md index 63b4386..877afd2 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,7 @@ process images and return the license plate information found in the image while > **I am not affiliated with ultimateALPR-SDK in any way, and I am not responsible for any misuse of the software.** > [!NOTE] -> The [ultimateALPR-SDK](https://github.com/DoubangoTelecom/ultimateALPR-SDK) is a lightweight and much faster alternative (on CPU and GPU) to existing solutions like -> [CodeProject AI](https://www.codeproject.com/AI/docs/index.html) but it has **one important restriction** with it's free version: +> The [ultimateALPR-SDK](https://github.com/DoubangoTelecom/ultimateALPR-SDK) is a lightweight and much faster alternative (on CPU and GPU) than existing solutions but it has **one important restriction** with it's free version: > - The last character of the license plate is masked with an asterisk *(e.g. ``ABC1234`` -> ``ABC123*``)* ## Installation @@ -35,40 +34,68 @@ The server listens on port 5000 and has a few endpoints documented below, the mo > POST: http://localhost:5000/v1/vision/alpr **Description** -This endpoint processes an image and returns the license plate information (if any) found in the image. -This endpoint follows -the [CodeProject AI ALPR API](https://www.codeproject.com/AI/docs/api/api_reference.html#license-plate-reader) format *( -example below)* so it can be used as a **drop-in replacement** for the CodeProject AI software. - +This endpoint processes an image and returns the license plate information (if any) found in the image. **Parameters** - upload: (File) The image file to process. *( see [Pillow.Image.open()](https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.open) for supported formats, almost any image format is supported)* - grid_size: (Integer, optional) Size of grid to divide the image into and retry on each cell when no match have been - found on the whole image *(default: 3)* **[(more info)](#more-information-about-the-grid-parameter)** -- wanted_cells: (String, optional) The cells you want to process *(default: all cells)* * - *[(see here)](#v1visionalpr_grid_debug)** - - format: ``1,2,3,4,...`` *(comma separated list of integers, max: grid_size^2)* + found on the whole image, must be ``>=2`` *(default: 0, disabled)* **[(more info)](#more-information-about-the-grid-parameter)** +- wanted_cells: (String, optional) The cells you want to process *(default: all cells)* **[(see here for more details)](#v1visionalpr_grid_debug)** + - format: ``1,2,3,4,...`` *(comma separated list of integers, max: ``grid_size^2``)* - *Example for a grid_size of 3:* ``` 1 | 2 | 3 4 | 5 | 6 7 | 8 | 9 ``` +- whole_image_fallback: (Boolean, optional) Only applies when ``grid_size`` is greater than 2. + If set to true, the server will first try to detect the plate from the ``wanted_cells`` parameter and if no plate is found, it will then try to detect the plate on the whole image. + If set to false, the server will only try to detect the plate on the specified cells. *(default: true)* **Response** ```jsonc { - "success": (Boolean) // True if successful. - "message": (String) // A summary of the inference operation. - "error": (String) // (Optional) An description of the error if success was false. - "predictions": (Object[]) // An array of objects with the x_max, x_min, max, y_min bounds of the plate, label, the plate chars and confidence. - "processMs": (Integer) // The time (ms) to process the image (includes inference and image manipulation operations). + "duration": (Float) // The time taken to process the image in milliseconds. + "plates": List // An array of plates found in the image. + "predictions": (Object[]) // An array of objects with the x_max, x_min, y_max, y_min bounds of the plate, image, the plate chars and confidence. } ``` +**Example** +```json +{ + "duration": 142.02, + "plates": [ + "XX12345*", + "YY5432*" + ], + "predictions": [ + { + "confidence": 0.9009034, + "image": "data:image/png;base64,xxxxx==", + "plate": "XX12345*", + "x_max": 680, + "x_min": 610, + "y_max": 386, + "y_min": 355 + }, + { + "confidence": 0.8930383999999999, + "image": "data:image/png;base64,xxxxx==", + "plate": "YY5432*", + "x_max": 680, + "x_min": 483, + "y_max": 706, + "y_min": 624 + } + ] +} +``` + + ### /v1/vision/alpr_grid_debug > POST: http://localhost:5000/v1/vision/alpr_grid_debug @@ -90,15 +117,10 @@ It is intended to be used for debugging purposes to see which cells are being pr ## More information about the grid parameter -When you send an image to the server, sometimes the ALPR software cannot find any plate because the image is too big or -the plate is too small in the image. -To solve this problem, if no plate is found on the whole image, the server will divide the image into a grid of cells -and retry the ALPR software on each cell. -You can specify the size of the grid with the ``grid_size`` parameter in each of your requests. -> [!CAUTION] -> The higher the grid size, the longer the processing time will be. It is recommended to keep the grid size between 3 -> and 4. -> Note: The processing time is in no way multiplied by the grid size (usually takes 2x the time) +Sometimes, the ALPR software cannot find any plate because the image is too big or the plate is too small in the image. +To solve this problem, you can make use of the ``grid_size`` parameter in each of your requests. +If you set the ``grid_size`` parameter to a value greater than 2, the server will divide the image into a grid of cells +and retry the ALPR software on each cell. You can speed up the processing time by specifying the ``wanted_cells`` parameter. This parameter allows you to specify which cells you want to run plate detection on. @@ -109,7 +131,7 @@ This can be useful if you know the plates can only be in certain areas of the im > You can then specify the ``wanted_cells`` parameter to only process the cells you want. **If you wish not to use the grid, you can set the ``grid_size`` parameter to -0 *(and leave the ``wanted_cells`` parameter empty)*.** +0 or leave it empty *(and leave the ``wanted_cells`` parameter empty)*.** ### Example