[DOCS] Add documentation for ImageField (#5448)

# Description
<!-- Please include a summary of the changes and the related issue.
Please also include relevant motivation and context. List any
dependencies that are required for this change. -->

Closes #<issue_number>

**Type of change**
<!-- Please delete options that are not relevant. Remember to title the
PR according to the type of change -->

- Bug fix (non-breaking change which fixes an issue)
- New feature (non-breaking change which adds functionality)
- Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- Refactor (change restructuring the codebase without changing
functionality)
- Improvement (change adding some improvement to an existing
functionality)
- Documentation update

**How Has This Been Tested**
<!-- Please add some reference about how your feature has been tested.
-->

**Checklist**
<!-- Please go over the list and make sure you've taken everything into
account -->

- I added relevant documentation
- I followed the style guidelines of this project
- I did a self-review of my code
- I made corresponding changes to the documentation
- I confirm My changes generate no new warnings
- I have added tests that prove my fix is effective or that my feature
works
- I have added relevant notes to the CHANGELOG.md file (See
https://keepachangelog.com/)

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: sdiazlor <[email protected]>

Author: 3 people

argilla/docs/how_to_guides/dataset.md

@@ -142,23 +142,36 @@ new_dataset.create()
 
 ### Fields
 
-The fields in a dataset consist of one or more data items requiring annotation. Currently, Argilla only supports plain text and markdown through the `TextField`, though we plan to introduce additional field types in future updates.
+The fields in a dataset consist of one or more data items requiring annotation. Currently, Argilla supports plain text and markdown through the `TextField` and images through the `ImageField`, though we plan to introduce additional field types in future updates.
 
 !!! note
     The order of the fields in the UI follows the order in which these are added to the fields attribute in the Python SDK.
 
 > Check the [Field - Python Reference](../reference/argilla/settings/fields.md) to see the field classes in detail.
 
-```python
-rg.TextField(
-    name="text",
-    title="Text",
-    use_markdown=False,
-    required=True,
-    description="Field description",
-)
-```
-![TextField](../assets/images/how_to_guides/dataset/fields.png)
+=== "Text"
+
+    ```python
+    rg.TextField(
+        name="text",
+        title="Text",
+        use_markdown=False,
+        required=True,
+        description="Field description",
+    )
+    ```
+    ![TextField](../assets/images/how_to_guides/dataset/fields.png)
+
+=== "Image"
+
+    ```python
+    rg.ImageField(
+        name="image",
+        title="Image",
+        required=True,
+        description="Field description",
+    )
+    ```
 
 ### Questions
 

argilla/docs/how_to_guides/image_field.md

@@ -189,6 +189,9 @@ The records alone can be exported from a dataset in Argilla.  This is useful if
 
 The records can be exported as a dictionary, a list of dictionaries, or a `Dataset` of the `datasets` package.
 
+!!! note "With images"
+    If your dataset includes images, the recommended approach for exporting records is to use the `to_datasets` method, which exports the images as rescaled PIL objects. With other methods, the images will be exported using the data URI schema.
+
 === "To a python dictionary"
 
     Records can be exported from `Dataset.records` as a dictionary. The `to_dict` method can be used to export records as a dictionary. You can specify the orientation of the dictionary output. You can also decide if to flatten or not the dictionary.

argilla/docs/how_to_guides/import_export.md

@@ -131,7 +131,7 @@ Records can also be updated using the `log` method with records that contain an
             metadata={"department": "toys"},
             id="2" # (1)
         ),
-    ] # (1)
+    ]
 
     dataset.records.log(records)
     ```
@@ -149,7 +149,7 @@ Records can also be updated using the `log` method with records that contain an
             "metadata": {"department": "toys"},
             "id": "2" # (1)
         },
-    ] # (1)
+    ]
 
     dataset.records.log(data)
     ```
@@ -175,6 +175,7 @@ Records can also be updated using the `log` method with records that contain an
     )
 
     ```
+
     1. The `id` field is required to identify the record to be updated. The `id` field must be unique for each record in the dataset. If the `id` field is not provided, the record will be added as a new record.
     2. Let's say that your data structure has keys `my_id` instead of `id`. You can use the `mapping` parameter to map the keys in the data structure to the fields in the dataset.
 
@@ -193,6 +194,57 @@ Records can also be updated using the `log` method with records that contain an
     1. In this example, the Hugging Face dataset matches the Argilla dataset schema.
     2. The `uuid` key in the Hugging Face dataset corresponds to the `id` field in the Argilla dataset.
 
+### Adding and updating records with images
+
+Argilla datasets can contain image fields. You can add images to a dataset by passing the image to the record object as either a remote URL, a local path to an image file, or a PIL object. The field names must be defined as an `rg.ImageField` in the dataset's `Settings` object to be accepted. Images will be stored in the Argilla database and returned using the data URI schema.
+
+!!! note "As PIL objects"
+    To retrieve the images as rescaled PIL objects, you can use the `to_datasets` method when exporting the records, as shown in this [how-to guide](../../../how_to_guides/import_export.md).
+
+=== "From a data structure with local file paths"
+
+    ```python
+
+    import os
+
+    image_dir = "path/to/images"
+
+    data = [
+        {
+            "image": os.path.join(image_dir, "image1.jpg"), # (1)
+        },
+        {
+            "image": os.path.join(image_dir, "image2.jpg"),
+        },
+    ]
+
+    dataset.records.log(data)
+    ```
+
+    1. The image can be referenced as either a remote URL, a local file path, or a PIL object.
+
+=== "From a Hugging Face dataset"
+
+    Hugging Face datasets can be passed directly to the `log` method. The image field must be defined as an `Image` in the dataset's features.
+
+    ```python
+    hf_dataset = load_dataset("ylecun/mnist", split="train[:100]")
+    dataset.records.log(records=hf_dataset)
+    ```
+
+    If the image field is not defined as an `Image` in the dataset's features, you can cast the dataset to the correct schema before adding it to the Argilla dataset. This is only necessary if the image field is not defined as an `Image` in the dataset's features, and is not one of the supported image types by Argilla (URL, local path, or PIL object).
+
+    ```python
+    hf_dataset = load_dataset("<my_custom_dataset>") # (1)
+    hf_dataset = hf_dataset.cast(
+        features=Features({"image": Image(), "label": Value("string")}),
+    )
+    dataset.records.log(records=hf_dataset)
+    ```
+
+    1. In this example, the Hugging Face dataset matches the Argilla dataset schema but the image field is not defined as an `Image` in the dataset's features.
+
+
 ### Iterating over records in a dataset
 
 `Dataset.records` can be used to iterate over records in a dataset from the server. The records will be fetched in batches from the server::

argilla/docs/reference/argilla/datasets/dataset_records.md

@@ -23,7 +23,7 @@ dataset.records.log(
 
 1. The Argilla dataset contains a field named `text` matching the key here.
 
-To create records with image fields, pass the the remote url or data uri of the image to records object. The field names must be defined as an `rg.ImageField`in the dataset's `Settings` object to be accepted.
+To create records with image fields, pass the image to the record object as either a remote url, local path to an image file, or a PIL object. The field names must be defined as an `rg.ImageField`in the dataset's `Settings` object to be accepted. Images will be stored in the Argilla database and returned as rescaled PIL objects.
 
 ```python
 dataset.records.log(
@@ -35,8 +35,10 @@ dataset.records.log(
 )
 ```
 
-1. The image can be referenced as either a remote url or a data uri.
+1. The image can be referenced as either a remote url, a local file path, or a PIL object.
 
+!!! note
+    The image will be stored in the Argilla database and can impact the dataset's storage usage. Images should be less than 5mb in size and datasets should contain less than 10,000 images.
 
 ### Accessing Record Attributes
 

argilla/docs/reference/argilla/records/records.md

@@ -42,3 +42,4 @@ data = rg.Dataset(
 
 
 ::: src.argilla.settings._field.TextField
+::: src.argilla.settings._field.ImageField