.. index:: 
  !Usage

.. _sdk_usage:

=========
Overview
=========

Naming conventions
==================

For the sake of clarity in this multi-language documentation, the following naming conventions have been adopted.

- Class, struct and enumeration names are written in *PascalCase*. Example: ``License``.
- Class and struct member names are written in *lowerCamelCase*. Example: ``activateSerialKey``
- Enumeration fields are written in *lowerCamelCase*. Example : ``LicenseError.invalidLicense``.

.. warning:: 
    The naming convention adopted in this documentation does not necessarily reflect the convention for a given programming language.
    More information is given below.
    

Conventions per programming language
------------------------------------

The following conventions apply:

.. tab-set::

    .. tab-item:: Python
        :sync: Python

        This SDK complies with the `PEP 8 recommendations <https://peps.python.org/pep-0008/>`_.

        - Class, struct and enumeration names are written in *PascalCase*.
        - Class and struct member names are written in *snake_case*.
        - Enumeration fields are written in *UPPER_CASE_WITH_UNDERSCORE*.

        **Examples:**

        - Class name: ``License``
        - Function name: ``activate_serial_key``
        - Structure: ``FacePoint``
        - Enumeration field: ``LicenseError.INVALID_LICENSE``

    .. tab-item:: Dart
        :sync: Dart

        - Class, struct and enumeration names are written in *PascalCase*.
        - Class and struct member names are written in *lowerCamelCase*.
        - Enumeration fields are written in *lowerCamelCase*.

        **Examples:**

        - Class name: ``License``
        - Function name: ``activateSerialKey``
        - Structure: ``FacePoint``
        - Enumeration field: ``LicenseError.invalidLicense``

    .. tab-item:: C#
        :sync: C#

        - Class, struct and enumeration names are written in *PascalCase*.
        - Class and struct member names are written in *PascalCase*.
        - Enumeration fields are written in *PascalCase*.

        **Examples:**

        - Class name: ``License``
        - Function name: ``ActivateSerialKey``
        - Structure: ``FacePoint``
        - Enumeration field: ``LicenseError.InvalidLicense``

    .. tab-item:: Java
        :sync: Java

        - Class name: ``License``
        - Function name: ``activateSerialKey``
        - Structure: ``FacePoint``
        - Enumeration field: ``LicenseError.INVALID_LICENSE``

    .. tab-item:: Kotlin
        :sync: Kotlin

        - Class name: ``License``
        - Function name: ``activateSerialKey``
        - Structure: ``FacePoint``
        - Enumeration field: ``LicenseError.INVALID_LICENSE``

    .. tab-item:: Swift
        :sync: Swift

        - Class name: ``License``
        - Function name: ``activateSerialKey``
        - Structure: ``FacePoint``
        - Enumeration field: ``LicenseError.invalidLicense``

    .. tab-item:: C
        :sync: C
        
        - Class name: ``id3License_``
        - Function name: ``id3License_ActivateSerialKey``
        - Structure: ``id3FacePoint``
        - Enumeration field: ``id3LicenseError_InvalidLicense`` 

        .. note:: 
            The C API implements pseudo object-oriented programming concepts where the object is passed explicitly to a member function as first parameter.



Adding the library to your project
==================================

.. tab-set::

    .. tab-item:: Windows

        The SDK relies on native libraries that must be copied to a ``bin`` subdirectory within your project's target directory.

        The following libraries are necessary:

        .. list-table:: 
            :width: 100%
            :widths: 30 70
            :header-rows: 1

            * - Library
              - Description

            * - ``id3Face.dll``
              - The main library for fingerprint processing and operations.
            
        To automate the process within Visual Studio, add a pre-build event to your project:

        - Right-click on your project in the Solution Explorer and select ``Properties``.
        - Go to the ``Build Events`` tab.
        - In the ``Pre-build event command line`` box, enter the following command:

            .. code-block:: none

                mkdir $(TargetDir)bin
                xcopy /e /y $(SolutionDir)..\..\bin\*.dll $(TargetDir)\bin

        This command copies all DLL files from the SDK's native library directory to the ``bin`` subdirectory of your project's target directory every time the project is built.

        Ensure the path ``$(SolutionDir)..\..\`` is correctly adjusted to point to the location where the SDK's native libraries are stored.

    .. tab-item:: Linux

        Add one of the following native library:

        * ``/bin/linux/x64/libid3Face.so``, or
        * ``/bin/linux/x64_gpu/libid3Face.so`` for CUDA support.

    .. tab-item:: Android

        Include the AAR package to your project:

        * ``/bin/android/eu.id3.face.aar``

    .. tab-item:: Apple

        Include the package in your project:

        1. **Unzip the Framework**:
            Unzip the ``/bin/apple/id3Face.xcframework.zip`` package to access the ``id3Face.xcframework`` directory.
        
        2. **Add the Framework to Xcode**:
            Open your Xcode project and drag the ``id3Face.xcframework`` directory into the "Frameworks, Libraries, and Embedded Content" section.
        
        3. **Update Build Settings**:
            Ensure that ``id3Face.xcframework`` is listed under "Link Binary with Libraries" in your target's "Build Phases".
            Set the "Framework Search Paths" in your target's "Build Settings" to include the path to ``id3Face.xcframework``.
        
        4. **Configure Code Signing**:
            Adjust the code signing settings in Xcode to allow the app to run with the included framework.
        
        5. **Handle Runtime Dependencies**:
            Ensure any additional runtime dependencies required by ``id3Face.xcframework`` are included.



Using the SDK in your project
==================================

.. tab-set::

    .. tab-item:: Python
        :sync: Python

        .. code-block:: python

            import id3face

    .. tab-item:: Dart
        :sync: Dart

        .. code-block:: dart

            import 'package:id3_face/id3_face.dart';

    .. tab-item:: C#
        :sync: C#

        .. code-block:: csharp

            using id3.Face;

    .. tab-item:: Java
        :sync: Java
   
        .. code-block:: java
        
            import eu.id3.face;

    .. tab-item:: C
        :sync: C

        .. code-block:: c

            #include "id3Face.h"


