Skip to content

Image Classification

nyckel.ImageClassificationFunction

Example:

from nyckel import Credentials, ImageClassificationFunction

credentials = Credentials(client_id="...", client_secret="...")

# Create new function
func = ImageClassificationFunction.create("IsCatOrDog", credentials)

# (or load existing function)
# func = ImageClassificationFunction("function_id", credentials)

# Create samples
func.create_samples([
    ("cat1.jpg", "cat"),
    ("cat2.jpg", "cat"),
    ("dog1.jpg", "dog"),
    ("dog2.jpg", "dog")
])

predictions = func.invoke(["cat_or_dog.jpg"])
Source code in src/nyckel/functions/classification/image_classification.py 
 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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
class ImageClassificationFunction(ClassificationFunction):
    """
    Example:

    ```py
    from nyckel import Credentials, ImageClassificationFunction

    credentials = Credentials(client_id="...", client_secret="...")

    # Create new function
    func = ImageClassificationFunction.create("IsCatOrDog", credentials)

    # (or load existing function)
    # func = ImageClassificationFunction("function_id", credentials)

    # Create samples
    func.create_samples([
        ("cat1.jpg", "cat"),
        ("cat2.jpg", "cat"),
        ("dog1.jpg", "dog"),
        ("dog2.jpg", "dog")
    ])

    predictions = func.invoke(["cat_or_dog.jpg"])
    ```
    """

    def __init__(self, function_id: str, credentials: Credentials) -> None:
        function_id = strip_nyckel_prefix(function_id)
        self._function_id = function_id
        self._function_handler = ClassificationFunctionHandler(function_id, credentials)
        self._label_handler = ClassificationLabelHandler(function_id, credentials)
        self._url_handler = ClassificationFunctionURLHandler(function_id, credentials.server_url)
        self._sample_handler = ClassificationSampleHandler(function_id, credentials)
        self._encoder = ImageEncoder()
        assert self._function_handler.get_input_modality() == "Image"

    def __str__(self) -> str:
        return self.__repr__()

    def __repr__(self) -> str:
        status_string = f"Name: {self.name}, id: {self.function_id}, url: {self._url_handler.train_page}"
        return status_string

    @property
    def function_id(self) -> NyckelId:
        return self._function_id

    @property
    def sample_count(self) -> int:
        return self._function_handler.sample_count

    @property
    def label_count(self) -> int:
        return self._function_handler.label_count

    @property
    def name(self) -> str:
        return self._function_handler.get_name()

    @classmethod
    def create(cls, name: str, credentials: Credentials) -> "ImageClassificationFunction":
        return factory.ClassificationFunctionFactory.create(name, "Image", credentials)  # type: ignore

    def delete(self) -> None:
        self._function_handler.delete()

    def invoke(  # type: ignore
        self, sample_data_list: List[ImageSampleData], model_id: str = ""
    ) -> List[ClassificationPredictionOrError]:
        return self._sample_handler.invoke(sample_data_list, ImageSampleBodyTransformer(), model_id=model_id)

    def has_trained_model(self) -> bool:
        return self._function_handler.is_trained

    def create_labels(self, labels: Sequence[Union[ClassificationLabel, str]]) -> List[NyckelId]:
        typed_labels = [
            label if isinstance(label, ClassificationLabel) else ClassificationLabel(name=label) for label in labels
        ]
        return self._label_handler.create_labels(typed_labels)

    def list_labels(self) -> List[ClassificationLabel]:
        return self._label_handler.list_labels(self.label_count)

    def read_label(self, label_id: NyckelId) -> ClassificationLabel:
        return self._label_handler.read_label(label_id)

    def update_label(self, label: ClassificationLabel) -> ClassificationLabel:
        return self._label_handler.update_label(label)

    def delete_labels(self, label_ids: List[NyckelId]) -> None:
        return self._label_handler.delete_labels(label_ids)

    def create_samples(  # type: ignore
        self,
        samples: Sequence[  # type: ignore
            Union[
                ImageClassificationSample,
                Tuple[Image.Image, LabelName],
                Image.Image,
                Tuple[ImageSampleData, LabelName],
                ImageSampleData,
            ]
        ],
    ) -> List[NyckelId]:
        typed_samples = self._wrangle_post_samples_input(samples)
        typed_samples = self._strip_label_names(typed_samples)
        self._create_labels_as_needed(typed_samples)

        return self._sample_handler.create_samples(typed_samples, ImageSampleBodyTransformer())

    def list_samples(self) -> List[ImageClassificationSample]:  # type: ignore
        samples_dict_list = self._sample_handler.list_samples(self.sample_count)
        labels = self._label_handler.list_labels(None)

        label_name_by_id = {label.id: label.name for label in labels}

        return [self._sample_from_dict(entry, label_name_by_id) for entry in samples_dict_list]

    def read_sample(self, sample_id: NyckelId) -> ImageClassificationSample:
        sample_dict = self._sample_handler.read_sample(sample_id)

        labels = self._label_handler.list_labels(None)
        label_name_by_id = {label.id: label.name for label in labels}

        return self._sample_from_dict(sample_dict, label_name_by_id)

    def update_annotation(self, sample: ImageClassificationSample) -> None:  # type: ignore
        self._sample_handler.update_annotation(sample)

    def delete_samples(self, sample_ids: List[NyckelId]) -> None:
        self._sample_handler.delete_samples(sample_ids)

    def _sample_from_dict(self, sample_dict: Dict, label_name_by_id: Dict) -> ImageClassificationSample:
        if "annotation" in sample_dict:
            annotation = ClassificationAnnotation(
                label_name=label_name_by_id[strip_nyckel_prefix(sample_dict["annotation"]["labelId"])],
            )
        else:
            annotation = None
        if "prediction" in sample_dict:
            prediction = ClassificationPrediction(
                confidence=sample_dict["prediction"]["confidence"],
                label_name=label_name_by_id[strip_nyckel_prefix(sample_dict["prediction"]["labelId"])],
            )
        else:
            prediction = None
        if "sampleSets" in sample_dict:
            sample_sets = []
            for sample_set_dict in sample_dict["sampleSets"]:
                sample_sets.append(ClassificationSampleSet(id=strip_nyckel_prefix(sample_set_dict["sampleSetId"])))
        else:
            sample_sets = None
        return ImageClassificationSample(
            id=strip_nyckel_prefix(sample_dict["id"]),
            data=sample_dict["data"],
            external_id=sample_dict["externalId"] if "externalId" in sample_dict else None,
            annotation=annotation,
            prediction=prediction,
            sample_sets=sample_sets,
        )

    def _wrangle_post_samples_input(
        self,
        samples: Sequence[
            Union[
                ImageSampleData,
                Image.Image,
                ImageClassificationSample,
                Tuple[ImageSampleData, LabelName],
                Tuple[Image.Image, LabelName],
            ]
        ],
    ) -> List[ImageClassificationSample]:
        typed_samples: List[ImageClassificationSample] = []
        for sample in samples:
            if isinstance(sample, str):
                typed_samples.append(ImageClassificationSample(data=sample))
            elif isinstance(sample, Image.Image):
                typed_samples.append(ImageClassificationSample(data=self._encoder.to_base64(sample)))
            elif isinstance(sample, (tuple, list)) and isinstance(sample[0], str):
                image_str, label_name = sample
                typed_samples.append(
                    ImageClassificationSample(
                        data=image_str, annotation=ClassificationAnnotation(label_name=label_name)
                    )
                )
            elif isinstance(sample, (tuple, list)) and isinstance(sample[0], Image.Image):
                image_pil, label_name = sample
                typed_samples.append(
                    ImageClassificationSample(
                        data=self._encoder.to_base64(image_pil),
                        annotation=ClassificationAnnotation(label_name=label_name),
                    )
                )
            elif isinstance(sample, ImageClassificationSample):
                typed_samples.append(sample)
            else:
                raise ValueError(f"Unknown sample type: {type(sample)}")
        return typed_samples

    def _create_labels_as_needed(self, samples: List[ImageClassificationSample]) -> None:
        existing_labels = self._label_handler.list_labels(None)
        existing_label_names = {label.name for label in existing_labels}
        new_label_names = {sample.annotation.label_name for sample in samples if sample.annotation}
        missing_label_names = new_label_names - existing_label_names
        missing_labels = [ClassificationLabel(name=label_name) for label_name in missing_label_names]
        if len(missing_labels) > 0:
            self._label_handler.create_labels(missing_labels)

    def _strip_label_names(self, samples: List[ImageClassificationSample]) -> List[ImageClassificationSample]:
        for sample in samples:
            if sample.annotation:
                sample.annotation.label_name = sample.annotation.label_name.strip()
        return samples

function_id property 

function_id: NyckelId

sample_count property 

sample_count: int

label_count property 

label_count: int

name property 

name: str

__init__ 

__init__(function_id: str, credentials: Credentials) -> None
Source code in src/nyckel/functions/classification/image_classification.py 
54
55
56
57
58
59
60
61
62
def __init__(self, function_id: str, credentials: Credentials) -> None:
    function_id = strip_nyckel_prefix(function_id)
    self._function_id = function_id
    self._function_handler = ClassificationFunctionHandler(function_id, credentials)
    self._label_handler = ClassificationLabelHandler(function_id, credentials)
    self._url_handler = ClassificationFunctionURLHandler(function_id, credentials.server_url)
    self._sample_handler = ClassificationSampleHandler(function_id, credentials)
    self._encoder = ImageEncoder()
    assert self._function_handler.get_input_modality() == "Image"

create classmethod 

create(name: str, credentials: Credentials) -> ImageClassificationFunction
Source code in src/nyckel/functions/classification/image_classification.py 
87
88
89
@classmethod
def create(cls, name: str, credentials: Credentials) -> "ImageClassificationFunction":
    return factory.ClassificationFunctionFactory.create(name, "Image", credentials)  # type: ignore

delete 

delete() -> None
Source code in src/nyckel/functions/classification/image_classification.py 
91
92
def delete(self) -> None:
    self._function_handler.delete()

invoke 

invoke(sample_data_list: List[ImageSampleData], model_id: str = '') -> List[ClassificationPredictionOrError]
Source code in src/nyckel/functions/classification/image_classification.py 
94
95
96
97
def invoke(  # type: ignore
    self, sample_data_list: List[ImageSampleData], model_id: str = ""
) -> List[ClassificationPredictionOrError]:
    return self._sample_handler.invoke(sample_data_list, ImageSampleBodyTransformer(), model_id=model_id)

has_trained_model 

has_trained_model() -> bool
Source code in src/nyckel/functions/classification/image_classification.py 
 99
100
def has_trained_model(self) -> bool:
    return self._function_handler.is_trained

create_labels 

create_labels(labels: Sequence[Union[ClassificationLabel, str]]) -> List[NyckelId]
Source code in src/nyckel/functions/classification/image_classification.py 
102
103
104
105
106
def create_labels(self, labels: Sequence[Union[ClassificationLabel, str]]) -> List[NyckelId]:
    typed_labels = [
        label if isinstance(label, ClassificationLabel) else ClassificationLabel(name=label) for label in labels
    ]
    return self._label_handler.create_labels(typed_labels)

list_labels 

list_labels() -> List[ClassificationLabel]
Source code in src/nyckel/functions/classification/image_classification.py 
108
109
def list_labels(self) -> List[ClassificationLabel]:
    return self._label_handler.list_labels(self.label_count)

read_label 

read_label(label_id: NyckelId) -> ClassificationLabel
Source code in src/nyckel/functions/classification/image_classification.py 
111
112
def read_label(self, label_id: NyckelId) -> ClassificationLabel:
    return self._label_handler.read_label(label_id)

update_label 

update_label(label: ClassificationLabel) -> ClassificationLabel
Source code in src/nyckel/functions/classification/image_classification.py 
114
115
def update_label(self, label: ClassificationLabel) -> ClassificationLabel:
    return self._label_handler.update_label(label)

delete_labels 

delete_labels(label_ids: List[NyckelId]) -> None
Source code in src/nyckel/functions/classification/image_classification.py 
117
118
def delete_labels(self, label_ids: List[NyckelId]) -> None:
    return self._label_handler.delete_labels(label_ids)

create_samples 

create_samples(samples: Sequence[Union[ImageClassificationSample, Tuple[Image, LabelName], Image, Tuple[ImageSampleData, LabelName], ImageSampleData]]) -> List[NyckelId]
Source code in src/nyckel/functions/classification/image_classification.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def create_samples(  # type: ignore
    self,
    samples: Sequence[  # type: ignore
        Union[
            ImageClassificationSample,
            Tuple[Image.Image, LabelName],
            Image.Image,
            Tuple[ImageSampleData, LabelName],
            ImageSampleData,
        ]
    ],
) -> List[NyckelId]:
    typed_samples = self._wrangle_post_samples_input(samples)
    typed_samples = self._strip_label_names(typed_samples)
    self._create_labels_as_needed(typed_samples)

    return self._sample_handler.create_samples(typed_samples, ImageSampleBodyTransformer())

list_samples 

list_samples() -> List[ImageClassificationSample]
Source code in src/nyckel/functions/classification/image_classification.py 
138
139
140
141
142
143
144
def list_samples(self) -> List[ImageClassificationSample]:  # type: ignore
    samples_dict_list = self._sample_handler.list_samples(self.sample_count)
    labels = self._label_handler.list_labels(None)

    label_name_by_id = {label.id: label.name for label in labels}

    return [self._sample_from_dict(entry, label_name_by_id) for entry in samples_dict_list]

read_sample 

read_sample(sample_id: NyckelId) -> ImageClassificationSample
Source code in src/nyckel/functions/classification/image_classification.py 
146
147
148
149
150
151
152
def read_sample(self, sample_id: NyckelId) -> ImageClassificationSample:
    sample_dict = self._sample_handler.read_sample(sample_id)

    labels = self._label_handler.list_labels(None)
    label_name_by_id = {label.id: label.name for label in labels}

    return self._sample_from_dict(sample_dict, label_name_by_id)

update_annotation 

update_annotation(sample: ImageClassificationSample) -> None
Source code in src/nyckel/functions/classification/image_classification.py 
154
155
def update_annotation(self, sample: ImageClassificationSample) -> None:  # type: ignore
    self._sample_handler.update_annotation(sample)

delete_samples 

delete_samples(sample_ids: List[NyckelId]) -> None
Source code in src/nyckel/functions/classification/image_classification.py 
157
158
def delete_samples(self, sample_ids: List[NyckelId]) -> None:
    self._sample_handler.delete_samples(sample_ids)

nyckel.ImageClassificationSample dataclass

Source code in src/nyckel/functions/classification/classification.py 
65
66
67
68
69
70
71
72
@dataclass
class ImageClassificationSample:
    data: ImageSampleData
    id: Optional[NyckelId] = None
    external_id: Optional[str] = None
    annotation: Optional[ClassificationAnnotation] = None
    prediction: Optional[ClassificationPrediction] = None
    sample_sets: Optional[List[ClassificationSampleSet]] = None

data instance-attribute 

data: ImageSampleData

id class-attribute instance-attribute 

id: Optional[NyckelId] = None

external_id class-attribute instance-attribute 

external_id: Optional[str] = None

annotation class-attribute instance-attribute 

annotation: Optional[ClassificationAnnotation] = None

prediction class-attribute instance-attribute 

prediction: Optional[ClassificationPrediction] = None

sample_sets class-attribute instance-attribute 

sample_sets: Optional[List[ClassificationSampleSet]] = None

__init__ 

__init__(data: ImageSampleData, id: Optional[NyckelId] = None, external_id: Optional[str] = None, annotation: Optional[ClassificationAnnotation] = None, prediction: Optional[ClassificationPrediction] = None, sample_sets: Optional[List[ClassificationSampleSet]] = None) -> None

nyckel.ImageSampleData module-attribute 

ImageSampleData = str

DataUri, Url, or local filepath.