Skip to content

Ascii2D

Classes

Ascii2D

Bases: BaseSearchEngine[Ascii2DResponse]

API client for the Ascii2D image search engine.

Ascii2D provides two search modes
  1. Color search: Finds images with similar color combinations (default mode)
  2. Feature search: Finds images with similar visual features (bovw mode)

Attributes:

Name Type Description
base_url str

The base URL for Ascii2D searches.
bovw bool

A flag to enable feature search mode.
Note
  • Color search (bovw=False) is recommended for finding visually similar images
  • Feature search (bovw=True) is better for:
    • Cropped images
    • Rotated images
    • Images with different color schemes
  • Feature search may be less accurate with heavily modified images
Source code in PicImageSearch/engines/ascii2d.py 
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
class Ascii2D(BaseSearchEngine[Ascii2DResponse]):
    """API client for the Ascii2D image search engine.

    Ascii2D provides two search modes:
        1. Color search: Finds images with similar color combinations (default mode)
        2. Feature search: Finds images with similar visual features (bovw mode)

    Attributes:
        base_url (str): The base URL for Ascii2D searches.
        bovw (bool): A flag to enable feature search mode.

    Note:
        - Color search (bovw=False) is recommended for finding visually similar images
        - Feature search (bovw=True) is better for:
            * Cropped images
            * Rotated images
            * Images with different color schemes
        - Feature search may be less accurate with heavily modified images
    """

    def __init__(
        self,
        base_url: str = "https://ascii2d.net",
        bovw: bool = False,
        **request_kwargs: Any,
    ):
        """Initializes an Ascii2D API client with specified configurations.

        Args:
            base_url (str): The base URL for Ascii2D searches.
            bovw (bool): If True, use feature search; otherwise, use color combination search.
            **request_kwargs (Any): Additional arguments for network requests.
        """
        base_url = f"{base_url}/search"
        super().__init__(base_url, **request_kwargs)
        self.bovw = bovw

    async def search(
        self,
        url: Optional[str] = None,
        file: Union[str, bytes, Path, None] = None,
        **kwargs: Any,
    ) -> Ascii2DResponse:
        """Performs a reverse image search on Ascii2D.

        This method supports two ways of searching:
            1. Search by image URL
            2. Search by uploading a local image file

        The search process involves:
            1. Initial submission of the image (URL or file)
            2. Optional switch to feature search mode if bovw=True
            3. Parsing and returning the search results

        Args:
            url (Optional[str]): URL of the image to search.
            file (Union[str, bytes, Path, None]): Local image file, can be a path string, bytes data, or Path object.
            **kwargs (Any): Additional arguments passed to the parent class.

        Returns:
            Ascii2DResponse: An object containing:
                - Search results with similar images
                - Source information and metadata
                - The final search URL

        Raises:
            ValueError: If neither `url` nor `file` is provided.

        Note:
            - Only one of `url` or `file` should be provided
            - Feature search (bovw) may take longer to process
        """
        self._validate_args(url, file)

        data: Optional[dict[str, Any]] = None
        files: Optional[dict[str, Any]] = None
        endpoint: str = "uri" if url else "file"

        if url:
            data = {"uri": url}
        elif file:
            files = {"file": read_file(file)}

        resp = await self._make_request(
            method="post",
            endpoint=endpoint,
            data=data,
            files=files,
        )

        # If 'bovw' is enabled, switch to feature search mode.
        if self.bovw:
            resp = await self.get(resp.url.replace("/color/", "/bovw/"))

        return Ascii2DResponse(resp.text, resp.url)

Attributes

bovw = bovw instance-attribute

Functions

__init__(base_url='https://ascii2d.net', bovw=False, **request_kwargs)

Initializes an Ascii2D API client with specified configurations.

Parameters:

Name Type Description Default
base_url str

The base URL for Ascii2D searches.

 'https://ascii2d.net'
bovw bool

If True, use feature search; otherwise, use color combination search.

 False
**request_kwargs Any

Additional arguments for network requests.

 {}
Source code in PicImageSearch/engines/ascii2d.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def __init__(
    self,
    base_url: str = "https://ascii2d.net",
    bovw: bool = False,
    **request_kwargs: Any,
):
    """Initializes an Ascii2D API client with specified configurations.

    Args:
        base_url (str): The base URL for Ascii2D searches.
        bovw (bool): If True, use feature search; otherwise, use color combination search.
        **request_kwargs (Any): Additional arguments for network requests.
    """
    base_url = f"{base_url}/search"
    super().__init__(base_url, **request_kwargs)
    self.bovw = bovw
search(url=None, file=None, **kwargs) async

Performs a reverse image search on Ascii2D.

This method supports two ways of searching
  1. Search by image URL
  2. Search by uploading a local image file
The search process involves
  1. Initial submission of the image (URL or file)
  2. Optional switch to feature search mode if bovw=True
  3. Parsing and returning the search results

Parameters:

Name Type Description Default
url Optional[str]

URL of the image to search.

 None
file Union[str, bytes, Path, None]

Local image file, can be a path string, bytes data, or Path object.

 None
**kwargs Any

Additional arguments passed to the parent class.

 {}

Returns:

Name Type Description
Ascii2DResponse Ascii2DResponse

An object containing: - Search results with similar images - Source information and metadata - The final search URL

Raises:

Type Description
ValueError

If neither url nor file is provided.
Note
  • Only one of url or file should be provided
  • Feature search (bovw) may take longer to process
Source code in PicImageSearch/engines/ascii2d.py 
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
async def search(
    self,
    url: Optional[str] = None,
    file: Union[str, bytes, Path, None] = None,
    **kwargs: Any,
) -> Ascii2DResponse:
    """Performs a reverse image search on Ascii2D.

    This method supports two ways of searching:
        1. Search by image URL
        2. Search by uploading a local image file

    The search process involves:
        1. Initial submission of the image (URL or file)
        2. Optional switch to feature search mode if bovw=True
        3. Parsing and returning the search results

    Args:
        url (Optional[str]): URL of the image to search.
        file (Union[str, bytes, Path, None]): Local image file, can be a path string, bytes data, or Path object.
        **kwargs (Any): Additional arguments passed to the parent class.

    Returns:
        Ascii2DResponse: An object containing:
            - Search results with similar images
            - Source information and metadata
            - The final search URL

    Raises:
        ValueError: If neither `url` nor `file` is provided.

    Note:
        - Only one of `url` or `file` should be provided
        - Feature search (bovw) may take longer to process
    """
    self._validate_args(url, file)

    data: Optional[dict[str, Any]] = None
    files: Optional[dict[str, Any]] = None
    endpoint: str = "uri" if url else "file"

    if url:
        data = {"uri": url}
    elif file:
        files = {"file": read_file(file)}

    resp = await self._make_request(
        method="post",
        endpoint=endpoint,
        data=data,
        files=files,
    )

    # If 'bovw' is enabled, switch to feature search mode.
    if self.bovw:
        resp = await self.get(resp.url.replace("/color/", "/bovw/"))

    return Ascii2DResponse(resp.text, resp.url)

Functions