morphiaone 0.2.2__tar.gz → 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: morphiaone
3
- Version: 0.2.2
3
+ Version: 0.4.0
4
4
  Summary: Python SDK for the MorphiaOne V1 API (Developer Preview): Skin Analysis, Makeup Try-On and Hair Color Try-On.
5
5
  Author: MorphiaOne
6
6
  License-Expression: MIT
@@ -30,8 +30,7 @@ Try-On and Hair Color Try-On, plus the Assets, Jobs and Usage calls they rest on
30
30
 
31
31
  > **Developer Preview.** The V1 API contract is release candidate `1.0.0-rc.1`, still a
32
32
  > draft, and this SDK may change before 1.0, including in ways that break code written
33
- > against it. Pin an exact version. `0.1.0` is published; this source tree is `0.2.2`,
34
- > which is not published until its release is approved.
33
+ > against it. Pin an exact version. `0.3.0` is the current published version.
35
34
 
36
35
  ## Install
37
36
 
@@ -115,14 +114,14 @@ Skin Analysis is a cosmetic reading, not a medical one.
115
114
 
116
115
  ## Makeup Try-On
117
116
 
118
- `products` is ordered, and the order is the layer order:
117
+ `applications` is kept in the order given:
119
118
 
120
119
  ```python
121
- from morphiaone import MakeupTryOnOutput
120
+ from morphiaone import MakeupTryOnOutput, semantic
122
121
 
123
122
  job = client.makeup.try_on(
124
123
  asset_id=source.id,
125
- products=[{"category": "lipstick", "color": "#C2185B", "opacity": 0.8}],
124
+ applications=[semantic.lipstick("#C2185B")],
126
125
  )
127
126
  done = client.jobs.wait(job.id)
128
127
  if isinstance(done.output, MakeupTryOnOutput):
@@ -131,6 +130,24 @@ if isinstance(done.output, MakeupTryOnOutput):
131
130
  out.write(image.content)
132
131
  ```
133
132
 
133
+ A shade you published in your catalogue is a variant application, named by its id.
134
+ The job's `resolution` names the variant revision it rendered:
135
+
136
+ ```python
137
+ from morphiaone import variant
138
+
139
+ job = client.makeup.try_on(source.id, [variant("var_...")])
140
+ print(job.resolution.applications[0].variant.revision)
141
+ ```
142
+
143
+ A curated look you published in your catalogue is sent by its id in place of
144
+ `applications`. The job's `resolution.look` names the revision it rendered:
145
+
146
+ ```python
147
+ job = client.makeup.try_on(source.id, look_id="look_...")
148
+ print(job.resolution.look.revision)
149
+ ```
150
+
134
151
  ## Hair Color Try-On
135
152
 
136
153
  Hair Color Try-On takes one source image: the server finds the hair and recolors only
@@ -5,8 +5,7 @@ Try-On and Hair Color Try-On, plus the Assets, Jobs and Usage calls they rest on
5
5
 
6
6
  > **Developer Preview.** The V1 API contract is release candidate `1.0.0-rc.1`, still a
7
7
  > draft, and this SDK may change before 1.0, including in ways that break code written
8
- > against it. Pin an exact version. `0.1.0` is published; this source tree is `0.2.2`,
9
- > which is not published until its release is approved.
8
+ > against it. Pin an exact version. `0.3.0` is the current published version.
10
9
 
11
10
  ## Install
12
11
 
@@ -90,14 +89,14 @@ Skin Analysis is a cosmetic reading, not a medical one.
90
89
 
91
90
  ## Makeup Try-On
92
91
 
93
- `products` is ordered, and the order is the layer order:
92
+ `applications` is kept in the order given:
94
93
 
95
94
  ```python
96
- from morphiaone import MakeupTryOnOutput
95
+ from morphiaone import MakeupTryOnOutput, semantic
97
96
 
98
97
  job = client.makeup.try_on(
99
98
  asset_id=source.id,
100
- products=[{"category": "lipstick", "color": "#C2185B", "opacity": 0.8}],
99
+ applications=[semantic.lipstick("#C2185B")],
101
100
  )
102
101
  done = client.jobs.wait(job.id)
103
102
  if isinstance(done.output, MakeupTryOnOutput):
@@ -106,6 +105,24 @@ if isinstance(done.output, MakeupTryOnOutput):
106
105
  out.write(image.content)
107
106
  ```
108
107
 
108
+ A shade you published in your catalogue is a variant application, named by its id.
109
+ The job's `resolution` names the variant revision it rendered:
110
+
111
+ ```python
112
+ from morphiaone import variant
113
+
114
+ job = client.makeup.try_on(source.id, [variant("var_...")])
115
+ print(job.resolution.applications[0].variant.revision)
116
+ ```
117
+
118
+ A curated look you published in your catalogue is sent by its id in place of
119
+ `applications`. The job's `resolution.look` names the revision it rendered:
120
+
121
+ ```python
122
+ job = client.makeup.try_on(source.id, look_id="look_...")
123
+ print(job.resolution.look.revision)
124
+ ```
125
+
109
126
  ## Hair Color Try-On
110
127
 
111
128
  Hair Color Try-On takes one source image: the server finds the hair and recolors only
@@ -7,9 +7,11 @@ asset = client.assets.upload("face.jpg")
7
7
  job = client.skin.analyze(asset.id, ["acne"], wait=True)
8
8
 
9
9
  event = webhooks.verify(raw_body, signature_header, endpoint_secret)
10
+
11
+ job = client.makeup.try_on(asset.id, [semantic.blush("#C27461")], wait=True)
10
12
  """
11
13
 
12
- from . import webhooks
14
+ from . import semantic, webhooks
13
15
  from .client import RetryPolicy
14
16
  from .errors import (
15
17
  ApiError,
@@ -39,6 +41,17 @@ from .v1 import (
39
41
  Asset,
40
42
  AssetContent,
41
43
  AsyncMorphiaOne,
44
+ CatalogueApplicationDefinition,
45
+ CatalogueLook,
46
+ CatalogueLookPinChange,
47
+ CatalogueLookReference,
48
+ CatalogueLookRepin,
49
+ CatalogueLookRevision,
50
+ CatalogueLookSemanticEntry,
51
+ CatalogueLookVariantEntry,
52
+ CatalogueVariant,
53
+ CatalogueVariantReferences,
54
+ CatalogueVariantRevision,
42
55
  CreditBalance,
43
56
  HairAppliedColorGradient,
44
57
  HairAppliedColorStop,
@@ -48,7 +61,15 @@ from .v1 import (
48
61
  JobInputRef,
49
62
  JobListItem,
50
63
  JobOutput,
64
+ MakeupResolution,
65
+ MakeupResolutionLook,
66
+ MakeupResolutionProfile,
67
+ MakeupResolutionTarget,
68
+ MakeupResolutionVariant,
69
+ MakeupResolutionWarning,
70
+ MakeupResolvedApplication,
51
71
  MakeupTryOnOutput,
72
+ MakeupTryOnResult,
52
73
  MorphiaOne,
53
74
  Page,
54
75
  ResultAssetRef,
@@ -57,6 +78,7 @@ from .v1 import (
57
78
  UnknownJobOutput,
58
79
  UsageReport,
59
80
  )
81
+ from .variants import variant
60
82
 
61
83
  __all__ = [
62
84
  "ApiError",
@@ -64,6 +86,17 @@ __all__ = [
64
86
  "AssetContent",
65
87
  "AsyncMorphiaOne",
66
88
  "AuthenticationError",
89
+ "CatalogueApplicationDefinition",
90
+ "CatalogueLook",
91
+ "CatalogueLookPinChange",
92
+ "CatalogueLookReference",
93
+ "CatalogueLookRepin",
94
+ "CatalogueLookRevision",
95
+ "CatalogueLookSemanticEntry",
96
+ "CatalogueLookVariantEntry",
97
+ "CatalogueVariant",
98
+ "CatalogueVariantReferences",
99
+ "CatalogueVariantRevision",
67
100
  "ConflictError",
68
101
  "CreditBalance",
69
102
  "DeadlineExceeded",
@@ -81,7 +114,15 @@ __all__ = [
81
114
  "JobNotSucceededError",
82
115
  "JobOutput",
83
116
  "JobStatus",
117
+ "MakeupResolution",
118
+ "MakeupResolutionLook",
119
+ "MakeupResolutionProfile",
120
+ "MakeupResolutionTarget",
121
+ "MakeupResolutionVariant",
122
+ "MakeupResolutionWarning",
123
+ "MakeupResolvedApplication",
84
124
  "MakeupTryOnOutput",
125
+ "MakeupTryOnResult",
85
126
  "MorphiaOne",
86
127
  "MorphiaOneError",
87
128
  "NotFoundError",
@@ -105,5 +146,7 @@ __all__ = [
105
146
  "ValidationError",
106
147
  "WebhookSignatureError",
107
148
  "parse_rate_limit",
149
+ "semantic",
150
+ "variant",
108
151
  "webhooks",
109
152
  ]
@@ -0,0 +1,125 @@
1
+ """Typed makeup applications for ``client.makeup.try_on(applications=...)``.
2
+
3
+ ``try_on`` accepts any mapping; these ``TypedDict`` s name what the API publishes so a
4
+ type checker can catch a misspelt field.
5
+
6
+ The ``Semantic*Product`` types are semantic mode: a category, a colour and the
7
+ category's declared options, resolved server-side (``morphiaone.semantic`` builds them).
8
+ ``VariantMakeupProduct`` names a shade your tenant registered in the catalogue
9
+ (``client.catalogue``); ``morphiaone.variant`` builds it. Explicit products are closed
10
+ to partners.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from typing import Literal, NotRequired, TypedDict
16
+
17
+
18
+ class _SemanticProduct(TypedDict):
19
+ """Semantic mode: the server resolves the texture and defaults from a versioned
20
+ profile. ``color`` is ``#RGB`` or ``#RRGGBB``; ``shade_name`` is descriptive only.
21
+ An option left out takes the category's server-side default (the comment names
22
+ today's); ``client.makeup.capabilities()`` lists the categories and values."""
23
+
24
+ mode: Literal["semantic"]
25
+ color: str
26
+ shade_name: NotRequired[str]
27
+
28
+
29
+ class SemanticFoundationProduct(_SemanticProduct):
30
+ category: Literal["foundation"]
31
+ intensity: NotRequired[Literal["medium", "strong"]] # default medium
32
+
33
+
34
+ class SemanticBlushProduct(_SemanticProduct):
35
+ category: Literal["blush"]
36
+ intensity: NotRequired[Literal["medium", "strong"]] # default medium
37
+
38
+
39
+ class SemanticContourProduct(_SemanticProduct):
40
+ category: Literal["contour"]
41
+ intensity: NotRequired[Literal["medium", "strong"]] # default medium
42
+
43
+
44
+ class SemanticEyelinerProduct(_SemanticProduct):
45
+ category: Literal["eyeliner"]
46
+ style: NotRequired[Literal["normal", "dark_matte"]] # default normal
47
+ intensity: NotRequired[Literal["medium", "strong"]] # default medium
48
+
49
+
50
+ class SemanticHighlighterProduct(_SemanticProduct):
51
+ category: Literal["highlighter"]
52
+ intensity: NotRequired[Literal["medium", "strong"]] # default medium
53
+
54
+
55
+ class SemanticMascaraProduct(_SemanticProduct):
56
+ category: Literal["mascara"]
57
+ style: NotRequired[
58
+ Literal[
59
+ "volume",
60
+ "curl",
61
+ "length",
62
+ "volume_curl",
63
+ "volume_length",
64
+ "curl_length",
65
+ "volume_curl_length",
66
+ ]
67
+ ] # default volume
68
+
69
+
70
+ class SemanticLipstickProduct(_SemanticProduct):
71
+ category: Literal["lipstick"]
72
+ finish: NotRequired[Literal["matte", "gloss", "metallic"]] # default matte
73
+
74
+
75
+ class SemanticLipLinerProduct(_SemanticProduct):
76
+ category: Literal["lip_liner"]
77
+ intensity: NotRequired[Literal["medium", "strong"]] # default medium
78
+
79
+
80
+ class SemanticConcealerProduct(_SemanticProduct):
81
+ category: Literal["concealer"]
82
+ intensity: NotRequired[Literal["medium", "strong"]] # default medium
83
+
84
+
85
+ class SemanticBronzerProduct(_SemanticProduct):
86
+ category: Literal["bronzer"]
87
+ intensity: NotRequired[Literal["medium", "strong"]] # default medium
88
+
89
+
90
+ class SemanticEyeshadowProduct(_SemanticProduct):
91
+ """One colour on the lids."""
92
+
93
+ category: Literal["eyeshadow"]
94
+ placement: NotRequired[Literal["lid"]] # default lid
95
+ intensity: NotRequired[Literal["medium", "strong"]] # default medium
96
+
97
+
98
+ SemanticMakeupProduct = (
99
+ SemanticFoundationProduct
100
+ | SemanticBlushProduct
101
+ | SemanticContourProduct
102
+ | SemanticEyelinerProduct
103
+ | SemanticHighlighterProduct
104
+ | SemanticMascaraProduct
105
+ | SemanticLipstickProduct
106
+ | SemanticLipLinerProduct
107
+ | SemanticConcealerProduct
108
+ | SemanticBronzerProduct
109
+ | SemanticEyeshadowProduct
110
+ )
111
+
112
+
113
+ class VariantMakeupProduct(TypedDict):
114
+ """Variant mode: a published variant of your catalogue, resolved server-side under
115
+ the profile version its current revision pinned. ``application_id`` names which of
116
+ the variant's applications to apply, and may be left out only when it declares one."""
117
+
118
+ mode: Literal["variant"]
119
+ variant_id: str
120
+ application_id: NotRequired[str]
121
+
122
+
123
+ MakeupProduct = SemanticMakeupProduct | VariantMakeupProduct
124
+
125
+ HairBlend = Literal["tint", "color", "overlay"]
@@ -0,0 +1,220 @@
1
+ """Semantic makeup products: a category, a colour and the category's options.
2
+
3
+ Semantic mode is the recommended makeup path. The server resolves each product through
4
+ the category's current, versioned profile, and the job's ``resolution`` names the
5
+ profile version, the shade and the options it resolved with::
6
+
7
+ from morphiaone import MorphiaOne, semantic
8
+
9
+ result = client.makeup.try_on_file(
10
+ "selfie.jpg",
11
+ [semantic.lipstick("#C27461", finish="gloss"), semantic.blush("#E8A0A0")],
12
+ )
13
+ result.image.content # the rendered image
14
+ result.resolution.applications[0].profile # the profile version it rendered with
15
+
16
+ These helpers only build the request dict. They hold no defaults: an option left out is
17
+ left out, and the server applies the category's declared default. A category or value
18
+ the server does not accept is refused with ``semantic_mode_unavailable`` or
19
+ ``unsupported_<field>``; ``client.makeup.capabilities()`` lists what is accepted.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ from typing import Any, Literal
25
+
26
+ from .products import (
27
+ SemanticBlushProduct,
28
+ SemanticBronzerProduct,
29
+ SemanticConcealerProduct,
30
+ SemanticContourProduct,
31
+ SemanticEyelinerProduct,
32
+ SemanticEyeshadowProduct,
33
+ SemanticFoundationProduct,
34
+ SemanticHighlighterProduct,
35
+ SemanticLipLinerProduct,
36
+ SemanticLipstickProduct,
37
+ SemanticMascaraProduct,
38
+ )
39
+
40
+ __all__ = [
41
+ "blush",
42
+ "bronzer",
43
+ "concealer",
44
+ "contour",
45
+ "eyeliner",
46
+ "eyeshadow",
47
+ "foundation",
48
+ "highlighter",
49
+ "lip_liner",
50
+ "lipstick",
51
+ "mascara",
52
+ ]
53
+
54
+
55
+ def _product(category: str, color: str, **options: Any) -> dict[str, Any]:
56
+ return {
57
+ "mode": "semantic",
58
+ "category": category,
59
+ "color": color,
60
+ **{name: value for name, value in options.items() if value is not None},
61
+ }
62
+
63
+
64
+ def foundation(
65
+ color: str,
66
+ *,
67
+ intensity: Literal["medium", "strong"] | None = None,
68
+ shade_name: str | None = None,
69
+ ) -> SemanticFoundationProduct:
70
+ """A semantic foundation (intensity: server default medium)."""
71
+
72
+ return _product( # type: ignore[return-value]
73
+ "foundation", color, shade_name=shade_name, intensity=intensity
74
+ )
75
+
76
+
77
+ def blush(
78
+ color: str,
79
+ *,
80
+ intensity: Literal["medium", "strong"] | None = None,
81
+ shade_name: str | None = None,
82
+ ) -> SemanticBlushProduct:
83
+ """A semantic blush (intensity: server default medium)."""
84
+
85
+ return _product( # type: ignore[return-value]
86
+ "blush", color, shade_name=shade_name, intensity=intensity
87
+ )
88
+
89
+
90
+ def contour(
91
+ color: str,
92
+ *,
93
+ intensity: Literal["medium", "strong"] | None = None,
94
+ shade_name: str | None = None,
95
+ ) -> SemanticContourProduct:
96
+ """A semantic contour (intensity: server default medium)."""
97
+
98
+ return _product( # type: ignore[return-value]
99
+ "contour", color, shade_name=shade_name, intensity=intensity
100
+ )
101
+
102
+
103
+ def eyeliner(
104
+ color: str,
105
+ *,
106
+ style: Literal["normal", "dark_matte"] | None = None,
107
+ intensity: Literal["medium", "strong"] | None = None,
108
+ shade_name: str | None = None,
109
+ ) -> SemanticEyelinerProduct:
110
+ """A semantic eyeliner (style: server default normal, intensity: server default medium)."""
111
+
112
+ return _product( # type: ignore[return-value]
113
+ "eyeliner", color, shade_name=shade_name, style=style, intensity=intensity
114
+ )
115
+
116
+
117
+ def highlighter(
118
+ color: str,
119
+ *,
120
+ intensity: Literal["medium", "strong"] | None = None,
121
+ shade_name: str | None = None,
122
+ ) -> SemanticHighlighterProduct:
123
+ """A semantic highlighter (intensity: server default medium)."""
124
+
125
+ return _product( # type: ignore[return-value]
126
+ "highlighter", color, shade_name=shade_name, intensity=intensity
127
+ )
128
+
129
+
130
+ def mascara(
131
+ color: str,
132
+ *,
133
+ style: Literal[
134
+ "volume",
135
+ "curl",
136
+ "length",
137
+ "volume_curl",
138
+ "volume_length",
139
+ "curl_length",
140
+ "volume_curl_length",
141
+ ]
142
+ | None = None,
143
+ shade_name: str | None = None,
144
+ ) -> SemanticMascaraProduct:
145
+ """A semantic mascara (style: server default volume)."""
146
+
147
+ return _product( # type: ignore[return-value]
148
+ "mascara", color, shade_name=shade_name, style=style
149
+ )
150
+
151
+
152
+ def lipstick(
153
+ color: str,
154
+ *,
155
+ finish: Literal["matte", "gloss", "metallic"] | None = None,
156
+ shade_name: str | None = None,
157
+ ) -> SemanticLipstickProduct:
158
+ """A semantic lipstick (finish: server default matte)."""
159
+
160
+ return _product( # type: ignore[return-value]
161
+ "lipstick", color, shade_name=shade_name, finish=finish
162
+ )
163
+
164
+
165
+ def lip_liner(
166
+ color: str,
167
+ *,
168
+ intensity: Literal["medium", "strong"] | None = None,
169
+ shade_name: str | None = None,
170
+ ) -> SemanticLipLinerProduct:
171
+ """A semantic lip liner (intensity: server default medium)."""
172
+
173
+ return _product( # type: ignore[return-value]
174
+ "lip_liner", color, shade_name=shade_name, intensity=intensity
175
+ )
176
+
177
+
178
+ def concealer(
179
+ color: str,
180
+ *,
181
+ intensity: Literal["medium", "strong"] | None = None,
182
+ shade_name: str | None = None,
183
+ ) -> SemanticConcealerProduct:
184
+ """A semantic concealer (intensity: server default medium)."""
185
+
186
+ return _product( # type: ignore[return-value]
187
+ "concealer", color, shade_name=shade_name, intensity=intensity
188
+ )
189
+
190
+
191
+ def bronzer(
192
+ color: str,
193
+ *,
194
+ intensity: Literal["medium", "strong"] | None = None,
195
+ shade_name: str | None = None,
196
+ ) -> SemanticBronzerProduct:
197
+ """A semantic bronzer (intensity: server default medium)."""
198
+
199
+ return _product( # type: ignore[return-value]
200
+ "bronzer", color, shade_name=shade_name, intensity=intensity
201
+ )
202
+
203
+
204
+ def eyeshadow(
205
+ color: str,
206
+ *,
207
+ placement: Literal["lid"] | None = None,
208
+ intensity: Literal["medium", "strong"] | None = None,
209
+ shade_name: str | None = None,
210
+ ) -> SemanticEyeshadowProduct:
211
+ """A one-colour semantic eyeshadow on the lids (placement: server default lid,
212
+ intensity: server default medium)."""
213
+
214
+ return _product( # type: ignore[return-value]
215
+ "eyeshadow",
216
+ color,
217
+ shade_name=shade_name,
218
+ placement=placement,
219
+ intensity=intensity,
220
+ )