EN | RU

flutter_image_cropper_aurora

The original ReadMe of the image_cropper plugin: README

Description

This plugin is an implementation of the image_cropper package for the Aurora operating system. This plugin is used for cropping images.

The plugin uses Dart code to provide a customizable visual interface for cropping images. However, the actual image cropping process is handled by the platform-specific component.

ReadMe of the usage example: README

Quick launch

    CroppedFile? resultImage =
        await ImageCropper()
            .cropImage(
                sourcePath: filePath,
                uiSettings: AuroraUiSettings(context: context),
            );

Contents

• Description
• Build and Install
• Detailed description
  • Dart Component
    • cropImage
    • recoverImage
    • AuroraUiSettings
  • C++ Component
    • Result Saving
• Branches
• Usage Example
• Compatibility
• Usage Rules

Build and Install

pubspec.yaml

dependencies:
    image_cropper: ^9.1.0
    image_cropper_aurora:
        path: https://developer.auroraos.ru/git/flutter/flutter-community-plugins/image_cropper_aurora.git

desktop

Permissions=UserDirs;

spec

BuildRequires: pkgconfig(Qt5Core)

main.cpp

#include <flutter/flutter_aurora.h>
#include <flutter/flutter_compatibility_qt.h> // <- Enable Qt
#include "generated_plugin_registrant.h"

int main(int argc, char *argv[]) {
    aurora::EnableQtCompatibility(); // <- Enable Qt
    aurora::Initialize(argc, argv);
    aurora::RegisterPlugins();
    aurora::Launch();
    return 0;
}

Detailed description

Dart component

cropImage

The cropImage method is designed for cropping images. It takes the path to the original image as input and returns the cropped image as a result. When this method is invoked, a new screen opens, allowing the user to interactively adjust the cropping area. The crop screen is implemented using the crop_image cross-platform plugin, which provides a flexible interface for cropping operations. When the cropImage method is called, it performs the following steps:

1. Path storage: The method accepts a sourcePath parameter, which specifies the path to the original image file. This path is stored in the _sourcePath variable internally. This storage mechanism allows the method to retain the reference to the source image for recovering the original image.
2. Dialog initialization: A crop screen is displayed, enabling the user to select and adjust the cropping area. This screen can be customized using the AuroraUiSettings configuration.
3. Delegation to Platform Plugin: Once the user confirms the cropping area, the method delegates the image processing and saving tasks to the platform component. The platform plugin is responsible for handling the actual cropping operation and saving the cropped image to a new file.
4. Result handling: The method gets the path to cropped image from platform component and returns a Future<CroppedFile?>, which resolves to a CroppedFile object representing the cropped image if the operation is successful. If the user cancels the operation or an error occurs, the method returns null.

recoverImage

The recoverImage method is designed to recover the source image that was previously set for cropping. This method is particularly useful when you need to retrieve the original image used during the last cropping operation without requiring the user to reselect it.

When invoked, the method checks whether a source image path (sourcePath) was provided during the last call to the cropImage method. If such a path is saved in _sourcePath, the method returns a CroppedFile object representing the source image. However, if no source image path is available, the method returns null.

It is important to note that this method does not perform any additional processing or recovery of previously cropped images. Its purpose is to provide access to the original source image that was set for cropping. The implementation of the method is straightforward. It checks whether the _sourcePath variable, which stores the path to the source image, is null. If _sourcePath is null, the method returns Future.value(null). Otherwise, it wraps the _sourcePath in a CroppedFile object and returns it as a future.

AuroraUiSettings

The AuroraUiSettings class provides a set of customization options for the image cropping dialog. This class extends the PlatformUiSettings class and allows developers to customize the cropping interface to match their application's design. You can read more about the possible settings here.

Passing the "context" argument for the Aurora OS is necessary so that the plugin can show the user a crop screen with image editing

Cpp Component

The C++-component is designed to handle calls to only one method: cropImage. This method is invoked when the user clicks the "crop" button in the crop screen of the Dart component. The cropImage method accepts a set of arguments that define the parameters for the cropping operation.

The mandatory arguments include:

• source_path: The path to the original image file.
• crop_top: The top boundary of the cropping area.
• crop_bottom: The bottom boundary of the cropping area.
• crop_left: The left boundary of the cropping area.
• crop_right: The right boundary of the cropping area.

These parameters are essential for defining the cropping region and ensuring that the platform component can process the image. Without these arguments, the cropping operation cannot be performed.

In addition to the mandatory arguments, the cropImage method also accepts several optional parameters. These include:

• max_width: The maximum width of the cropped image.
• max_height: The maximum height of the cropped image.
• ratio_x: The x-component of the aspect ratio for the cropping area.
• ratio_y: The y-component of the aspect ratio for the cropping area.
• compress_format: The format in which the cropped image will be compressed (jpg, png).
• compress_quality: The quality level for image compression, ranging from 0 to 100.
• rotation: The rotation angle applied to the image during cropping.

If these optional parameters are not provided, they will either be replaced with default values or will not influence the result of the cropping operation. For example, if max_width and max_height are not specified, the cropped image will retain its original dimensions, constrained by the cropping boundaries. Similarly, if compress_format or compress_quality is omitted, the platform component will use default compression settings.

These parameters are passed to the platform component via MethodChannel to perform the actual image processing and saving tasks.

It should be noted that the visual interface allows the user to select an area larger than the maxWidth and maxHeight passed to the cropImage method. In this case, after cropping by coordinates, the image will be cropped to the maximum length and width relative to its center and then cropped to the specified aspect ratio.

Result saving

The cropImage method saves the cropped image as a new image, following a specific naming and storage convention. The output file path is generated using a predefined template that ensures uniqueness and consistency. Each cropped image is saved in the user's Pictures directory, with the file name prefixed by ImageCropper- followed by a timestamp in the format yyyy-MM-dd-HH-mm-ss. The timestamp is dynamically generated based on the current date and time to avoid filename conflicts. The complete output path is constructed by appending the generated filename and the specified compression format (jpg or png) to the base directory path, which is defined as the home directory's Pictures folder. Example: ImageCropper-2025-04-17-15-05-08.jpg.

Usage example

You can find an example here.

Branches

The versions of the application comply with the branch naming convention, which can be found here

Compatibility

• Aurora OS: 5.1.3+

Usage Rules

• The source code of the project is provided under the license, that allows it to be used in third-party applications.
• To participate in the development of the project, please read the contributor agreement. If you plan to contribute your own source code to the project, you will need to accept the CLA agreement.
• For information about contributors see AUTHORS.
• Code of conduct is a current set of rules of the Open Mobile Platform which informs you how we expect the members of the community will interact while contributing and communicating.