fathomnet-py

https://fathomnet-py.readthedocs.io/en/latest/
Admin
A Python client API for interacting with FathomNet Database data, enabling scientists and...
Tokens:24,268
Snippets:243
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install fathomnet-py

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/index.rst.txt

Install the fathomnet-py library using pip. This is the standard method for adding the package to your Python environment.

```bash
$ python -m pip install fathomnet
```

--------------------------------

### Count Mode Output Example

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/scripts.rst.txt

Example output from the count mode, showing the number of boxes for a given concept and its descendants.

```text
concept                |  # boxes
-----------------------|---------
Bathochordaeus         |     1901
Bathochordaeus charon  |       99
Bathochordaeus mcnutti |     1259
Bathochordaeus stygius |     2471
```

--------------------------------

### Example Pascal VOC XML Annotation File

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/scripts.rst.txt

A sample XML file generated in Pascal VOC format, showing bounding box information for different object classes within an image.

```xml
<annotation>
    <folder>3007</folder>
    <filename>00_10_24_26.png</filename>
    <path>https://database.fathomnet.org/static/m3/framegrabs/Ventana/images/3007/00_10_24_26.png</path>
    <source>
        <database>FathomNet</database>
    </source>
    <size>
        <width>720</width>
        <height>368</height>
        <depth>3</depth>
    </size>
    <segmented>0</segmented>
    <object>
        <name>Bathochordaeus inner filter</name>
        <pose>Unspecified</pose>
        <truncated>0</truncated>
        <difficult>0</difficult>
        <occluded>0</occluded>
        <bndbox>
        <xmin>578</xmin>
        <xmax>601</xmax>
        <ymin>158</ymin>
        <ymax>185</ymax>
        </bndbox>
    </object>
    <object>
        <name>Apolemia</name>
        <pose>Unspecified</pose>
        <truncated>0</truncated>
        <difficult>0</difficult>
        <occluded>0</occluded>
        <bndbox>
        <xmin>2</xmin>
        <xmax>516</xmax>
        <ymin>113</ymin>
        <ymax>366</ymax>
        </bndbox>
    </object>
</annotation>
```

--------------------------------

### Example Pascal VOC Annotation Structure

Source: https://fathomnet-py.readthedocs.io/en/latest/scripts.html

An excerpt from a generated Pascal VOC XML file, showing the annotation structure for an image.

```xml
<annotation>
    <folder>3007</folder>
    <filename>00_10_24_26.png</filename>
    <path>https://database.fathomnet.org/static/m3/framegrabs/Ventana/images/3007/00_10_24_26.png</path>
    <source>
        <database>FathomNet</database>

```

--------------------------------

### Count Annotations for a Taxon

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/scripts.rst.txt

Run the script in count mode using the --count flag to get the number of annotations for a specified concept or taxon without generating output files. This is a dry run to estimate dataset size.

```bash
fathomnet-generate --count --concepts 'Bathochordaeus' --taxa fathomnet
```

--------------------------------

### fathomnet.api.worms.find_taxa_by_prefix

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves WoRMS taxa nodes that start with a given prefix, with optional filtering by rank and parent.

```APIDOC
## fathomnet.api.worms.find_taxa_by_prefix

### Description
Get all taxa nodes that start with a prefix.

### Method
Not specified (likely GET)

### Endpoint
Not specified

### Parameters
#### Query Parameters
- **_prefix** (str) - Required - The prefix to search for.
- **_rank** (str) - Optional - The taxonomic rank to filter by.
- **_parent** (str) - Optional - The parent name to filter by.

### Request Example
None specified.

### Response
#### Success Response
- **List[WormsNode]** - A list of WoRMS taxa nodes matching the criteria.
```

--------------------------------

### fathomnet.api.worms.get_ancestors_names

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Gets a list of names of all ancestors for a given WoRMS name, starting from the root.

```APIDOC
## fathomnet.api.worms.get_ancestors_names

### Description
Get all ancestors’ names of a given name.

### Method
Not specified (likely GET)

### Endpoint
Not specified

### Parameters
#### Query Parameters
- **_name** (str) - Required - The name to find ancestors for.

### Request Example
None specified.

### Response
#### Success Response
- **List[str]** - A list of ancestor names.
```

--------------------------------

### Generate Annotations with All Bounding Boxes

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/scripts.rst.txt

Use the --all flag to include all bounding boxes in an image, not just those for specified concepts. This is useful for a comprehensive dataset.

```bash
fathomnet-generate --output /path/to/output --concepts 'Bathochordaeus' -v --all
```

--------------------------------

### fathomnet.api.worms.get_parent_name

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Gets the name of the parent taxa node for a given WoRMS name.

```APIDOC
## fathomnet.api.worms.get_parent_name

### Description
Get the parent’s name of a given name.

### Method
Not specified (likely GET)

### Endpoint
Not specified

### Parameters
#### Query Parameters
- **_name** (str) - Required - The name to find the parent's name for.

### Request Example
None specified.

### Response
#### Success Response
- **str** - The name of the parent taxa node.
```

--------------------------------

### fathomnet.api.worms.get_children_names

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Gets a list of names of all direct children for a given WoRMS name.

```APIDOC
## fathomnet.api.worms.get_children_names

### Description
Get all children’s names of a given name.

### Method
Not specified (likely GET)

### Endpoint
Not specified

### Parameters
#### Query Parameters
- **_name** (str) - Required - The name to find children for.

### Request Example
None specified.

### Response
#### Success Response
- **List[str]** - A list of children's names.
```

--------------------------------

### X-API-Key Module

Source: https://fathomnet-py.readthedocs.io/en/latest/index.html

Handles authentication using API keys.

```APIDOC
## X-API-Key Module

### Description
Handles authentication using API keys.

### Methods
#### `auth(api_key: str)`

Authenticates the user with the provided API key.

### Parameters
#### Path Parameters
- `api_key` (str) - Required - Your FathomNet API key.

### Returns
- `AuthHeader`: An authentication header object containing the token.
```

--------------------------------

### X-API-Key Module

Source: https://fathomnet-py.readthedocs.io/en/latest?badge=latest

Handles authentication using API keys.

```APIDOC
## X-API-Key Module

### Description
Handles authentication using API keys.

### Methods
#### `auth(api_key)`

- **Description**: Authenticates with the FathomNet API using an provided API key.
- **Parameters**:
  - `api_key` (string): Your FathomNet API key.
- **Returns**: An `AuthHeader` object containing the authentication token.

### Example
```python
from fathomnet.api import xapikey

# Replace 'YOUR_API_KEY' with your actual API key
auth_header = xapikey.auth('YOUR_API_KEY')
print(f"Auth Type: {auth_header.type}, Token: {auth_header.token[:10]}...")
```
```

--------------------------------

### fathomnet.api.geoimages.count

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Gets a constrained count of geo images based on provided constraints.

```APIDOC
## fathomnet.api.geoimages.count

### Description
Get a constrained count of geo images.

### Method
POST

### Endpoint
/geoimages/count

### Parameters
#### Request Body
- **_geo_image_constraints** (GeoImageConstraints) - Required - Constraints for filtering geo images.
```

--------------------------------

### fathomnet.api.worms.get_descendants_names

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Gets a list of names of all descendants for a given WoRMS name, with an option to include only accepted names.

```APIDOC
## fathomnet.api.worms.get_descendants_names

### Description
Get all descendants’ names of a given name.

### Method
Not specified (likely GET)

### Endpoint
Not specified

### Parameters
#### Query Parameters
- **_name** (str) - Required - The name to find descendants for.
- **_accepted** (bool) - Optional - If True, only include accepted names. Defaults to False.

### Request Example
None specified.

### Response
#### Success Response
- **List[str]** - A list of descendant names.
```

--------------------------------

### Authenticate using X-API-Key

Source: https://fathomnet-py.readthedocs.io/en/latest/index.html

Demonstrates how to authenticate with the FathomNet API using an API key. Requires importing the xapikey module and providing a valid API key.

```python
>>> from fathomnet.api import xapikey
>>> xapikey.auth('NuCLjlNUlgHchtgDB01Sp1fABJVcWR')  # your API key here
AuthHeader(
   type='Bearer',
   token='eyJhbGciOiJI...'
)
```

--------------------------------

### Generate Dataset from Concepts File

Source: https://fathomnet-py.readthedocs.io/en/latest/scripts.html

Generates Pascal VOC XML files using a list of concepts provided in a text file. Verbose output and taxonomy extension are enabled.

```text
Bathochordaeus charon
Bathochordaeus mcnutti
Bathochordaeus stygius

```

```bash
fathomnet-generate --output /path/to/output --concepts-file concepts.txt -v --taxa fathomnet
```

--------------------------------

### List All Concepts

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves a list of all available concepts within the system.

```python
fathomnet.api.boundingboxes.find_concepts() -> List[str]
```

--------------------------------

### Bounding Boxes - Bulk Create

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Upload a CSV file to create multiple bounding boxes at once.

```APIDOC
## fathomnet.api.boundingboxes.upload_csv()

### Description
Upload a CSV of bounding boxes.

### Method
POST (inferred)

### Endpoint
/boundingboxes/upload (inferred)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **_csv_fp** (BinaryIO) - Required - A file-like object containing the CSV data.
- **_auth_header** (AuthHeader | None) - Optional - Authentication header.

### Request Example
```json
{
  "_csv_fp": "file_content_as_bytes",
  "_auth_header": { ... } 
}
```

### Response
#### Success Response (200)
- **Message** - A message indicating the status of the upload.

#### Response Example
```json
{
  "message": "string"
}
```
```

--------------------------------

### Authenticate with X-API-Key

Source: https://fathomnet-py.readthedocs.io/en/latest?badge=latest

Demonstrates how to authenticate using an API key with the xapikey module. Replace 'NuCLjlNUlgHchtgDB01Sp1fABJVcWR' with your actual API key. The output is an AuthHeader object containing the token type and the authentication token.

```python
from fathomnet.api import xapikey
xapikey.auth('NuCLjlNUlgHchtgDB01Sp1fABJVcWR')  # your API key here
# Expected output: AuthHeader(
#    type='Bearer',
#    token='eyJhbGciOiJI...'
# )
```

--------------------------------

### Generate Dataset from Concepts File

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/scripts.rst.txt

Generates a Pascal VOC dataset using a file that lists concepts, one per line. This is recommended for larger queries. Use -v for verbose output and --taxa for taxonomy.

```text
Bathochordaeus charon
Bathochordaeus mcnutti
Bathochordaeus stygius
```

```bash
fathomnet-generate --output /path/to/output --concepts-file concepts.txt -v --taxa fathomnet
```

--------------------------------

### fathomnet.api.imagesetuploads.find_rejection_reasons

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves a list of all rejection reasons for image set uploads.

```APIDOC
## fathomnet.api.imagesetuploads.find_rejection_reasons

### Description
Get a list of all rejection reasons.

### Method
GET

### Endpoint
/imagesetuploads/rejection_reasons

### Parameters
#### Query Parameters
None

### Response
#### Success Response (200)
- **reasons** (List[str]) - A list of rejection reason strings.
```

--------------------------------

### Find Concepts using Bounding Boxes API

Source: https://fathomnet-py.readthedocs.io/en/latest?badge=latest

Demonstrates how to find available concepts using the bounding boxes module. Requires importing the boundingboxes module from fathomnet.api.

```python
from fathomnet.api import boundingboxes
boundingboxes.find_concepts()
# Expected output: ['2G Robotics structured light laser', '55-gallon drum', ...]
```

--------------------------------

### Generate Dataset with Taxonomy Provider

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/scripts.rst.txt

Generates a Pascal VOC dataset including species within specified genera by using the 'fathomnet' taxonomy provider. This provider incorporates WoRMS and MBARI DSG taxonomies.

```bash
fathomnet-generate --output /path/to/output --concepts 'Abraliopsis,Bathochordaeus' -v --taxa fathomnet
```

--------------------------------

### Download Images with Dataset Generation

Source: https://fathomnet-py.readthedocs.io/en/latest/scripts.html

The --img-download flag specifies a directory to save downloaded images. Images are renamed by FathomNet UUID.

```bash
fathomnet-generate --output /path/to/output --img-download /path/to/output/images --concepts 'Abraliopsis' -v

```

```text
INFO:root:Creating output directory /home/kbarnard/Desktop/test/images
INFO:root:Successfully parsed flags
INFO:root:Concept(s) specified:
INFO:root:-
INFO:root:Abraliopsis
INFO:root:Fetching image records for 1 concept(s)...
INFO:root:Found 59 unique images with bounding boxes
INFO:root:Wrote 59 VOC files to /path/to/output
100% (59 of 59) |################################| Elapsed Time: 0:00:03 Time:  0:00:03
INFO:root:Downloaded 59 new images to /path/to/output/images

```

--------------------------------

### Generate Pascal VOC Dataset for a Single Concept

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/scripts.rst.txt

Generates a Pascal VOC dataset for a specified concept and writes it to the output directory. Use the -v flag to see verbose output during generation.

```bash
fathomnet-generate --output /path/to/output --concepts 'Abraliopsis'
```

```bash
fathomnet-generate --output /path/to/output --concepts 'Abraliopsis' -v
```

--------------------------------

### Generate Pascal VOC Dataset for Multiple Concepts

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/scripts.rst.txt

Generates a Pascal VOC dataset for multiple specified concepts. The --concepts flag accepts a comma-separated list. Use -v for verbose output.

```bash
fathomnet-generate --output /path/to/output --concepts 'Abraliopsis,Bathochordaeus' -v
```

--------------------------------

### List All User Defined Keys

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves a list of all user-defined keys used for bounding boxes.

```python
fathomnet.api.boundingboxes.find_all_user_defined_keys() -> List[str]
```

--------------------------------

### fathomnet.api.imagesetuploads.count_all

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Counts all image set uploads in the system.

```APIDOC
## fathomnet.api.imagesetuploads.count_all

### Description
Count all image set uploads.

### Method
GET

### Endpoint
/imagesetuploads/count

### Parameters
#### Query Parameters
None

### Response
#### Success Response (200)
- **count** (Count) - The total count of image set uploads.
```

--------------------------------

### Activity

Source: https://fathomnet-py.readthedocs.io/en/latest/dto.html

Represents an activity or event. Includes attribution, content, data, and topic.

```APIDOC
## Activity

### Description
Represents an activity or event. Includes attribution, content, data, and topic.

### Fields
- **attributedTo** (string) - Optional - The entity to which the activity is attributed.
- **content** (string) - Optional - The content of the activity.
- **data** (object) - Optional - Associated data for the activity.
- **lastUpdated** (string) - Optional - Timestamp of the last update.
- **model_config** (object) - Optional - Model configuration details.
- **topic** (string) - Optional - The topic of the activity.
```

--------------------------------

### fathomnet.api.stats.image_set_upload_positions

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves a list of image set upload positions.

```APIDOC
## fathomnet.api.stats.image_set_upload_positions

### Description
Get a list of image set upload positions.

### Method
GET

### Endpoint
/stats/imagesetuploadpositions

### Parameters
#### Query Parameters
None

### Response
#### Success Response (200)
- **positions** (List[ImageSetUploadPosition]) - A list of image set upload positions.
```

--------------------------------

### Create Bounding Box

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Creates a new bounding box. Requires a BoundingBoxDTO object and optionally an authentication header.

```python
fathomnet.api.boundingboxes.create_with_dto(_bounding_box : BoundingBoxDTO_, _auth_header : AuthHeader | None = None_) -> BoundingBoxDTO
```

--------------------------------

### Download Images During Annotation Generation

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/scripts.rst.txt

Use the --img-download option to specify a directory where images should be saved. The script will download images and rename them using their FathomNet UUID, avoiding re-downloads of existing files.

```text
fathomnet-generate --output /path/to/output --img-download /path/to/output/images --concepts 'Abraliopsis' -v
```

--------------------------------

### Bounding Boxes - Create, Update, Delete

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Operations for creating, updating, and deleting individual bounding boxes.

```APIDOC
## fathomnet.api.boundingboxes.create_with_dto()

### Description
Create a bounding box.

### Method
POST (inferred)

### Endpoint
/boundingboxes (inferred)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **_bounding_box** (BoundingBoxDTO) - Required - The bounding box data.
- **_auth_header** (AuthHeader | None) - Optional - Authentication header.

### Request Example
```json
{
  "_bounding_box": { ... },
  "_auth_header": { ... } 
}
```

### Response
#### Success Response (200)
- **BoundingBoxDTO** - The created bounding box object.

#### Response Example
```json
{
  "uuid": "string",
  "user_defined_key": "string",
  "concept": "string",
  "observer": "string",
  "created_at": "string",
  "updated_at": "string"
}
```
```

```APIDOC
## fathomnet.api.boundingboxes.update()

### Description
Update a bounding box.

### Method
PUT (inferred)

### Endpoint
/boundingboxes/{uuid} (inferred)

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The UUID of the bounding box to update.

#### Query Parameters
None

#### Request Body
- **_bounding_box** (ABoundingBoxDTO) - Required - The updated bounding box data.
- **_auth_header** (AuthHeader | None) - Optional - Authentication header.

### Request Example
```json
{
  "_bounding_box": { ... },
  "_auth_header": { ... } 
}
```

### Response
#### Success Response (200)
- **BoundingBoxDTO** - The updated bounding box object.

#### Response Example
```json
{
  "uuid": "string",
  "user_defined_key": "string",
  "concept": "string",
  "observer": "string",
  "created_at": "string",
  "updated_at": "string"
}
```
```

```APIDOC
## fathomnet.api.boundingboxes.delete()

### Description
Delete a bounding box.

### Method
DELETE (inferred)

### Endpoint
/boundingboxes/{uuid} (inferred)

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The UUID of the bounding box to delete.

#### Query Parameters
None

#### Request Body
- **_auth_header** (AuthHeader | None) - Optional - Authentication header.

### Request Example
```json
{
  "_auth_header": { ... } 
}
```

### Response
#### Success Response (200)
- (No specific return type mentioned, likely void or a success message)

#### Response Example
(No example provided)
```

--------------------------------

### Bounding Boxes - List & Count

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieve lists of concepts, observers, user-defined keys, and counts of bounding boxes.

```APIDOC
## fathomnet.api.boundingboxes.find_concepts()

### Description
Get a list of all concepts.

### Method
GET (inferred)

### Endpoint
/concepts (inferred)

### Parameters
None

### Request Example
(No example provided)

### Response
#### Success Response (200)
- **List[str]** - A list of concept names.

#### Response Example
```json
["concept1", "concept2"]
```
```

```APIDOC
## fathomnet.api.boundingboxes.find_observers()

### Description
Get a list of all observers.

### Method
GET (inferred)

### Endpoint
/observers (inferred)

### Parameters
None

### Request Example
(No example provided)

### Response
#### Success Response (200)
- **List[str]** - A list of observer names.

#### Response Example
```json
["observer1", "observer2"]
```
```

```APIDOC
## fathomnet.api.boundingboxes.find_all_user_defined_keys()

### Description
Get a list of all user-defined keys.

### Method
GET (inferred)

### Endpoint
/userdefinedkeys (inferred)

### Parameters
None

### Request Example
(No example provided)

### Response
#### Success Response (200)
- **List[str]** - A list of user-defined keys.

#### Response Example
```json
["key1", "key2"]
```
```

```APIDOC
## fathomnet.api.boundingboxes.count_all()

### Description
Get a count of all bounding boxes.

### Method
GET (inferred)

### Endpoint
/boundingboxes/count (inferred)

### Parameters
None

### Request Example
(No example provided)

### Response
#### Success Response (200)
- **Count** - An object containing the total count.

#### Response Example
```json
{
  "count": 12345
}
```
```

```APIDOC
## fathomnet.api.boundingboxes.count_by_concept()

### Description
Get a count of bounding boxes for a specific concept.

### Method
GET (inferred)

### Endpoint
/boundingboxes/count?concept={concept} (inferred)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **concept** (str) - Required - The concept to count bounding boxes for.

#### Request Body
None

### Request Example
(No example provided)

### Response
#### Success Response (200)
- **ByConceptCount** - An object containing the count for the specified concept.

#### Response Example
```json
{
  "concept": "string",
  "count": 123
}
```
```

```APIDOC
## fathomnet.api.boundingboxes.count_total_by_concept()

### Description
Get a count of bounding boxes for each concept.

### Method
GET (inferred)

### Endpoint
/boundingboxes/count/total_by_concept (inferred)

### Parameters
None

### Request Example
(No example provided)

### Response
#### Success Response (200)
- **List[ByConceptCount]** - A list of objects, each containing a concept and its bounding box count.

#### Response Example
```json
[
  {
    "concept": "concept1",
    "count": 100
  },
  {
    "concept": "concept2",
    "count": 200
  }
]
```
```

--------------------------------

### Find Taxa Children using Taxa API

Source: https://fathomnet-py.readthedocs.io/en/latest/index.html

Illustrates how to find child taxa for a given parent, using 'fathomnet' as the source and 'Bathochordaeus' as the parent. Requires importing the taxa module.

```python
>>> from fathomnet.api import taxa
>>> taxa.find_children('fathomnet', 'Bathochordaeus')
[
   Taxa(name='Bathochordaeus stygius', rank='species'),
   Taxa(name='Bathochordaeus charon', rank='species'),
   Taxa(name='Bathochordaeus mcnutti', rank='species')
]
```

--------------------------------

### Bounding Boxes Module

Source: https://fathomnet-py.readthedocs.io/en/latest?badge=latest

Provides functions to interact with bounding box data, including finding concepts associated with bounding boxes.

```APIDOC
## Bounding Boxes Module

### Description
Provides functions to interact with bounding box data, including finding concepts associated with bounding boxes.

### Methods
#### `find_concepts()`

- **Description**: Retrieves a list of concepts for which bounding boxes are available.
- **Usage**: `boundingboxes.find_concepts()`

### Example
```python
from fathomnet.api import boundingboxes

concepts = boundingboxes.find_concepts()
print(concepts)
```
```

--------------------------------

### fathomnet.api.images.create_if_not_exists

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Creates an image if it does not already exist. Requires authentication.

```APIDOC
## fathomnet.api.images.create_if_not_exists

### Description
Create an image if it doesn’t exist.

### Method
POST

### Endpoint
/images/create_if_not_exists

### Parameters
#### Request Body
- **_images** (List[Image]) - Required - A list of images to create.
#### Headers
- **_auth_header** (AuthHeader) - Optional - Authentication header.
```

--------------------------------

### Bounding Boxes Module

Source: https://fathomnet-py.readthedocs.io/en/latest/index.html

Provides functionality to interact with bounding box data, including finding concepts associated with bounding boxes.

```APIDOC
## Bounding Boxes Module

### Description
Provides functionality to interact with bounding box data, including finding concepts associated with bounding boxes.

### Methods
#### `find_concepts()`

Finds all concepts associated with bounding boxes.

### Returns
- `list[str]`: A list of concept names.
```

--------------------------------

### Generate Dataset in COCO Format

Source: https://fathomnet-py.readthedocs.io/en/latest/scripts.html

Use the --format flag to specify COCO output. This command generates a COCO-formatted dataset file.

```bash
fathomnet-generate --output /path/to/output --concepts 'Bathochordaeus' -v --format coco

```

```text
INFO:root:Successfully parsed flags
INFO:root:Concept(s) specified:
INFO:root:-
INFO:root:Bathochordaeus
INFO:root:Fetching image records for 1 concept(s)...
INFO:root:Found 1301 unique images with bounding boxes
INFO:root:Wrote COCO dataset to /path/to/output/dataset.json

```

--------------------------------

### Find Concepts

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/index.rst.txt

Use this snippet to retrieve a list of all available concepts in the FathomNet database.

```python
>>> from fathomnet.api import boundingboxes
>>> boundingboxes.find_concepts()
['2G Robotics structured light laser', '55-gallon drum', ...]
```

--------------------------------

### Find Images by Concept using Images API

Source: https://fathomnet-py.readthedocs.io/en/latest/index.html

Shows how to retrieve image data associated with a specific concept, such as 'Nanomia'. Requires importing the images module and returns AImageDTO objects.

```python
>>> from fathomnet.api import images
>>> images.find_by_concept('Nanomia')
[
   AImageDTO(
      id=2274942,
      uuid='cdbfca66-284f-48ac-a36f-7b2ac2b43533',
      url='https://database.fathomnet.org/static/m3/framegrabs/MiniROV/images/0056/02_18_37_20.png',
      ...
   ),
   ...
]
```

--------------------------------

### Find Images by Concept using Images API

Source: https://fathomnet-py.readthedocs.io/en/latest?badge=latest

Shows how to retrieve images associated with a specific concept, such as 'Nanomia'. This requires importing the images module from fathomnet.api. The output includes AImageDTO objects with details like id, uuid, and url.

```python
from fathomnet.api import images
images.find_by_concept('Nanomia')
# Expected output: [
#    AImageDTO(
#       id=2274942,
#       uuid='cdbfca66-284f-48ac-a36f-7b2ac2b43533',
#       url='https://database.fathomnet.org/static/m3/framegrabs/MiniROV/images/0056/02_18_37_20.png',
#       ...
#    ),
#    ...
# ]
```

--------------------------------

### Find Bounding Boxes by User Defined Key

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves a list of bounding boxes associated with a specific user-defined key.

```python
fathomnet.api.boundingboxes.find_by_user_defined_key(_user_defined_key : str_) -> List[BoundingBoxDTO]
```

--------------------------------

### fathomnet.api.users.create_new_api_key

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Creates a new API key for the authenticated user. Requires authentication.

```APIDOC
## fathomnet.api.users.create_new_api_key

### Description
Create a new API key for a user.

### Method
POST

### Endpoint
/users/me/apikey

### Parameters
#### Request Body
- **_auth_header_** (AuthHeader | None) - Optional - Authentication header.
```

--------------------------------

### Image Set Uploads API

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/api.rst.txt

Operations for managing image set uploads, including finding collections, images by UUID, and contributors, as well as counting uploads and rejection reasons.

```APIDOC
## Image Set Uploads API

### Description
Provides functions for managing image set uploads and related statistics.

### Functions
- `find_collections()`: Retrieves a list of image set collections.
- `find_by_image_uuid(uuid)`: Finds image set uploads associated with an image UUID.
- `find_by_contributor(email)`: Finds image set uploads by contributor email.
- `find_by_uuid(uuid)`: Finds an image set upload by its UUID.
- `find_rejection_reasons()`: Lists reasons for image set upload rejections.
- `find_contributors()`: Lists contributors of image set uploads.
- `count_all()`: Counts the total number of image set uploads.
- `stats()`: Computes statistics for image set uploads.
```

--------------------------------

### Images Module

Source: https://fathomnet-py.readthedocs.io/en/latest?badge=latest

Allows searching and retrieving image data based on concepts.

```APIDOC
## Images Module

### Description
Allows searching and retrieving image data based on concepts.

### Methods
#### `find_by_concept(concept_name)`

- **Description**: Finds images associated with a specific concept.
- **Parameters**:
  - `concept_name` (string): The name of the concept to search for.
- **Returns**: A list of `AImageDTO` objects representing the found images.

### Example
```python
from fathomnet.api import images

images_list = images.find_by_concept('Nanomia')
for img in images_list:
    print(f"Image ID: {img.id}, URL: {img.url}")
```
```

--------------------------------

### AImageDTO.to_pascal_voc

Source: https://fathomnet-py.readthedocs.io/en/latest/dto.html

Converts image data to the Pascal VOC XML format. This is useful for integrating with computer vision models that expect this format.

```APIDOC
## AImageDTO.to_pascal_voc

### Description
Converts image data to the Pascal VOC XML format. This is useful for integrating with computer vision models that expect this format.

### Method
`to_pascal_voc`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **str**: Pascal VOC encoded string

#### Response Example
None

ERROR HANDLING:
- **ValueError**: Raised if both the path and image URL are unspecified
```

--------------------------------

### fathomnet.api.worms.find_names_by_prefix

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Finds all WoRMS names that begin with a specified prefix.

```APIDOC
## fathomnet.api.worms.find_names_by_prefix

### Description
Get all names that start with a prefix.

### Method
Not specified (likely GET)

### Endpoint
Not specified

### Parameters
#### Query Parameters
- **_prefix** (str) - Required - The prefix to search for.

### Request Example
None specified.

### Response
#### Success Response
- **List[str]** - A list of names matching the prefix.
```

--------------------------------

### Bounding Boxes - Find

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieve bounding boxes using their user-defined key or UUID.

```APIDOC
## fathomnet.api.boundingboxes.find_by_user_defined_key()

### Description
Get a list of bounding boxes by a user-defined key.

### Method
GET (inferred)

### Endpoint
/boundingboxes?user_defined_key={user_defined_key} (inferred)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **user_defined_key** (str) - Required - The user-defined key to filter by.

#### Request Body
None

### Request Example
(No example provided)

### Response
#### Success Response (200)
- **List[BoundingBoxDTO]** - A list of bounding box objects.

#### Response Example
```json
[
  {
    "uuid": "string",
    "user_defined_key": "string",
    "concept": "string",
    "observer": "string",
    "created_at": "string",
    "updated_at": "string"
  }
]
```
```

```APIDOC
## fathomnet.api.boundingboxes.find_by_uuid()

### Description
Get a bounding box by UUID.

### Method
GET (inferred)

### Endpoint
/boundingboxes/{uuid} (inferred)

### Parameters
#### Path Parameters
- **uuid** (str) - Required - The UUID of the bounding box to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
(No example provided)

### Response
#### Success Response (200)
- **BoundingBoxDTO** - The bounding box object.

#### Response Example
```json
{
  "uuid": "string",
  "user_defined_key": "string",
  "concept": "string",
  "observer": "string",
  "created_at": "string",
  "updated_at": "string"
}
```
```

--------------------------------

### fathomnet.api.users.verify

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Verifies the authentication token and returns its contents. Requires authentication.

```APIDOC
## fathomnet.api.users.verify

### Description
Get the contents of an authorization token.

### Method
GET

### Endpoint
/users/verify

### Parameters
#### Request Body
- **_auth_header_** (AuthHeader | None) - Optional - Authentication header.
```

--------------------------------

### fathomnet.api.imagesetuploads.find_collections

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves a paged list of all image set uploads.

```APIDOC
## fathomnet.api.imagesetuploads.find_collections

### Description
Get a paged list of all image set uploads.

### Method
GET

### Endpoint
/imagesetuploads/collections

### Parameters
#### Query Parameters
- **_pageable** (Pageable) - Optional - Pagination information.
```

--------------------------------

### List All Observers

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves a list of all observers recorded in the system.

```python
fathomnet.api.boundingboxes.find_observers() -> List[str]
```

--------------------------------

### Find Images by Concept

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/index.rst.txt

Retrieve image data, including URLs and metadata, associated with a specific concept.

```python
>>> from fathomnet.api import images
>>> images.find_by_concept('Nanomia')
[
   AImageDTO(
      id=2274942, 
      uuid='cdbfca66-284f-48ac-a36f-7b2ac2b43533', 
      url='https://database.fathomnet.org/static/m3/framegrabs/MiniROV/images/0056/02_18_37_20.png', 
      ...
   ),
   ...]
```

--------------------------------

### Authenticate with API Key

Source: https://fathomnet-py.readthedocs.io/en/latest/_sources/index.rst.txt

Authenticate your requests to the FathomNet API using an API key to obtain an authorization token.

```python
>>> from fathomnet.api import xapikey
>>> xapikey.auth('NuCLjlNUlgHchtgDB01Sp1fABJVcWR')  # your API key here
   AuthHeader(
      type='Bearer',
      token='eyJhbGciOiJI...'
   )
```

--------------------------------

### Find Taxa Children using Taxa API

Source: https://fathomnet-py.readthedocs.io/en/latest?badge=latest

Illustrates how to find child taxa for a given parent, using 'fathomnet' as the source and 'Bathochordaeus' as the parent. Requires importing the taxa module from fathomnet.api. The results are Taxa objects with name and rank.

```python
from fathomnet.api import taxa
taxa.find_children('fathomnet', 'Bathochordaeus')
# Expected output: [
#    Taxa(name='Bathochordaeus stygius', rank='species'),
#    Taxa(name='Bathochordaeus charon', rank='species'),
#    Taxa(name='Bathochordaeus mcnutti', rank='species')
# ]
```

--------------------------------

### fathomnet.api.tags.create_with_dto

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Creates a new tag using a TagDTO object. Requires authentication.

```APIDOC
## fathomnet.api.tags.create_with_dto

### Description
Create a tag.

### Method
POST

### Endpoint
/tags

### Parameters
#### Request Body
- **_tag_** (TagDTO) - Required - The tag data transfer object.
- **_auth_header_** (AuthHeader | None) - Optional - Authentication header.
```

--------------------------------

### Images Module

Source: https://fathomnet-py.readthedocs.io/en/latest/index.html

Enables searching and retrieving image data based on concepts.

```APIDOC
## Images Module

### Description
Enables searching and retrieving image data based on concepts.

### Methods
#### `find_by_concept(concept: str)`

Finds images related to a specific concept.

### Parameters
#### Path Parameters
- `concept` (str) - Required - The concept to search for.

### Returns
- `list[AImageDTO]`: A list of image data transfer objects.
```

--------------------------------

### BoundingBox

Source: https://fathomnet-py.readthedocs.io/en/latest/dto.html

Represents a bounding box with associated metadata, similar to ABoundingBoxDTO but potentially for a different context.

```APIDOC
## BoundingBox

### Description
Represents a bounding box with associated metadata, similar to ABoundingBoxDTO but potentially for a different context.

### Fields
- **altConcept** (string) - Optional - An alternative concept identifier.
- **concept** (string) - Optional - The primary concept identifier.
- **createdTimestamp** (string) - Optional - The timestamp when the bounding box was created.
- **groupOf** (boolean) - Optional - Indicates if this bounding box represents a group.
- **height** (number) - Required - The height of the bounding box.
- **id** (integer) - Optional - The unique identifier for the bounding box.
- **image** (string) - Optional - The identifier of the associated image.
- **lastReviewedTimestamp** (string) - Optional - The timestamp of the last review.
- **lastUpdatedTimestamp** (string) - Optional - The timestamp of the last update.
- **model_config** (object) - Optional - Model configuration details.
- **observer** (string) - Optional - The identifier of the observer.
- **occluded** (boolean) - Optional - Indicates if the object is occluded.
- **reviewState** (string) - Optional - The current review state of the bounding box.
- **reviewer** (string) - Optional - The identifier of the reviewer.
- **truncated** (boolean) - Optional - Indicates if the bounding box is truncated.
- **userDefinedKey** (string) - Optional - A user-defined key for the bounding box.
- **uuid** (string) - Optional - The universally unique identifier for the bounding box.
- **width** (number) - Required - The width of the bounding box.
- **x** (number) - Required - The x-coordinate of the top-left corner.
- **y** (number) - Required - The y-coordinate of the top-left corner.
```

--------------------------------

### fathomnet.api.imagesetuploads.stats

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves statistics for a specific image set upload using its UUID.

```APIDOC
## fathomnet.api.imagesetuploads.stats

### Description
Get image set upload statistics for a corresponding image set upload UUID.

### Method
GET

### Endpoint
/imagesetuploads/{_image_set_upload_uuid_}/stats

### Parameters
#### Path Parameters
- **_image_set_upload_uuid_** (str) - Required - The UUID of the image set upload.
```

--------------------------------

### Upload Bounding Boxes CSV

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Uploads a CSV file containing bounding box data. Requires a file-like object for the CSV and an optional authentication header.

```python
fathomnet.api.boundingboxes.upload_csv(_csv_fp : BinaryIO_, _auth_header : AuthHeader | None = None_) -> Message
```

--------------------------------

### fathomnet.api.users.find_expertise

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves a list of all available expertise levels for users.

```APIDOC
## fathomnet.api.users.find_expertise

### Description
Get a list of all expertise levels.

### Method
GET

### Endpoint
/users/expertise

### Parameters
#### Query Parameters
None

### Response
#### Success Response (200)
- **expertise** (List[str]) - A list of expertise level strings.
```

--------------------------------

### fathomnet.api.geoimages.find_by_image_set_upload_uuid

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves a list of geo images corresponding to a specific image set upload UUID.

```APIDOC
## fathomnet.api.geoimages.find_by_image_set_upload_uuid

### Description
Get a list of geo images corresponding to an image set upload UUID.

### Method
GET

### Endpoint
/geoimages/by_image_set_upload_uuid/{_image_set_upload_uuid}

### Parameters
#### Path Parameters
- **_image_set_upload_uuid** (str) - Required - The UUID of the image set upload.
#### Query Parameters
- **_limit** (int) - Optional - The maximum number of results to return.
- **_offset** (int) - Optional - The number of results to skip.
```

--------------------------------

### AImageDTO

Source: https://fathomnet-py.readthedocs.io/en/latest/dto.html

Represents an image with associated metadata. Includes details about dimensions, location, timestamps, and associated bounding boxes.

```APIDOC
## AImageDTO

### Description
Represents an image with associated metadata. Includes details about dimensions, location, timestamps, and associated bounding boxes.

### Fields
- **altitude** (number) - Optional - The altitude of the image in meters.
- **boundingBoxes** (array) - Optional - A list of bounding boxes associated with the image.
- **contributorsEmail** (array) - Optional - A list of email addresses of contributors.
- **createdTimestamp** (string) - Optional - The timestamp when the image was created.
- **depthMeters** (number) - Optional - The depth in meters.
- **height** (integer) - Required - The height of the image in pixels.
- **id** (integer) - Optional - The unique identifier for the image.
- **imagingType** (string) - Optional - The type of imaging used.
- **lastUpdatedTimestamp** (string) - Optional - The timestamp of the last update.
- **lastValidation** (string) - Optional - Information about the last validation.
- **latitude** (number) - Optional - The latitude coordinate.
- **longitude** (number) - Optional - The longitude coordinate.
- **mediaType** (string) - Optional - The media type of the image.
- **model_config** (object) - Optional - Model configuration details.
- **modified** (string) - Optional - Timestamp of modification.
- **oxygenMlL** (number) - Optional - Oxygen level in ml/L.
- **pressureDbar** (number) - Optional - Pressure in decibars.
- **salinity** (number) - Optional - Salinity value.
- **sha256** (string) - Optional - The SHA256 hash of the image file.
- **tags** (array) - Optional - A list of tags associated with the image.
- **temperatureCelsius** (number) - Optional - Temperature in Celsius.
- **timestamp** (string) - Optional - The timestamp when the image was captured.
- **to_pascal_voc** (function) - Optional - A method to convert to Pascal VOC format.
- **url** (string) - Optional - The URL of the image.
- **uuid** (string) - Optional - The universally unique identifier for the image.
- **valid** (boolean) - Optional - Indicates if the image data is valid.
- **width** (integer) - Required - The width of the image in pixels.
```

--------------------------------

### fathomnet.api.imagesetuploads.find_by_image_uuid

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves an image set upload by its associated image UUID.

```APIDOC
## fathomnet.api.imagesetuploads.find_by_image_uuid

### Description
Get an image set upload by UUID.

### Method
GET

### Endpoint
/imagesetuploads/by_image_uuid/{_image_uuid}

### Parameters
#### Path Parameters
- **_image_uuid** (str) - Required - The UUID of the image.
```

--------------------------------

### Count Annotations for a Concept

Source: https://fathomnet-py.readthedocs.io/en/latest/scripts.html

Use the --count flag for a dry run to see the number of annotations without generating a dataset. All other output flags are available.

```bash
fathomnet-generate --count --concepts 'Bathochordaeus' --taxa fathomnet

```

```text
concept                |  # boxes
-----------------------|---------
Bathochordaeus         |     1901
Bathochordaeus charon  |       99
Bathochordaeus mcnutti |     1259
Bathochordaeus stygius |     2471

```

--------------------------------

### fathomnet.api.imagesetuploads.find_by_contributor

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves a list of image set uploads by a specific contributor's email address.

```APIDOC
## fathomnet.api.imagesetuploads.find_by_contributor

### Description
Get a list of image set uploads by contributor.

### Method
GET

### Endpoint
/imagesetuploads/by_contributor/{_contributors_email}

### Parameters
#### Path Parameters
- **_contributors_email** (str) - Required - The email address of the contributor.
```

--------------------------------

### BoundingBoxComment

Source: https://fathomnet-py.readthedocs.io/en/latest/dto.html

Represents a comment or flag associated with a bounding box.

```APIDOC
## BoundingBoxComment

### Description
Represents a comment or flag associated with a bounding box.

### Fields
- **alternateConcept** (string) - Optional - An alternative concept identifier for the comment.
- **boundingBoxUuid** (string) - Required - The UUID of the bounding box this comment is associated with.
- **createdTimestamp** (string) - Optional - The timestamp when the comment was created.
- **email** (string) - Optional - The email address of the commenter.
- **flagged** (boolean) - Optional - Indicates if the bounding box is flagged.
- **lastUpdatedTimestamp** (string) - Optional - The timestamp of the last update.
- **model_config** (object) - Optional - Model configuration details.
```

--------------------------------

### Audit Bounding Box by User Defined Key

Source: https://fathomnet-py.readthedocs.io/en/latest/api.html

Retrieves the audit history for a bounding box using its user-defined key.

```python
fathomnet.api.boundingboxes.audit_by_user_defined_key(_user_defined_key : str_) -> List[BoundingBoxDTO]
```
Tokens:
Raw