Skip to content

Commit fe8780e

Browse files
loong10kloong10k
committed
merge: resolve pom.xml conflict by accepting remote changes
2 parents a2a98e3 + 060a99d commit fe8780e

27 files changed

Lines changed: 920 additions & 37 deletions

‎.github/workflows/ci.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# CI workflow for the main line (JDK 17)
2+
#
3+
# Triggers:
4+
# - push / pull_request on the main branch
5+
# - manual workflow_dispatch
6+
#
7+
# Runs `mvn -B clean verify` which includes the JaCoCo coverage gate
8+
# (90% line coverage, haltOnFailure=false) configured in the POM.
9+
name: CI
10+
11+
on:
12+
push:
13+
branches: [main]
14+
pull_request:
15+
branches: [main]
16+
workflow_dispatch:
17+
18+
permissions:
19+
contents: read
20+
21+
jobs:
22+
build:
23+
name: JDK 17 Build & Verify
24+
runs-on: ubuntu-latest
25+
timeout-minutes: 30
26+
steps:
27+
- name: Checkout source
28+
uses: actions/checkout@v7
29+
30+
- name: Set up JDK 17
31+
uses: actions/setup-java@v5
32+
with:
33+
distribution: temurin
34+
java-version: '17'
35+
cache: maven
36+
37+
- name: Build and verify with JaCoCo coverage gate
38+
run: mvn -B --no-transfer-progress clean verify
39+
40+
- name: Upload JaCoCo coverage report
41+
if: always()
42+
uses: actions/upload-artifact@v7
43+
with:
44+
name: jacoco-coverage
45+
path: target/site/jacoco
46+
retention-days: 14
47+
48+
- name: Upload surefire reports
49+
if: always()
50+
uses: actions/upload-artifact@v7
51+
with:
52+
name: surefire-reports
53+
path: target/surefire-reports
54+
retention-days: 14

‎README.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
# faceplusplus-java-sdk
2+
3+
[English](./README.md) | [简体中文](./README.zh-CN.md)
4+
5+
[![Java](https://img.shields.io/badge/Java-17-orange)](https://github.com/easy-4-java/faceplusplus-java-sdk) [![License](https://img.shields.io/badge/license-Apache%202.0-green)](https://www.apache.org/licenses/LICENSE-2.0.txt)
6+
7+
A Java SDK for the Face++ (Megvii) face recognition API. Template-style operations for face detection, analysis, comparison, search, skin analysis and faceset (face group) management, powered by OkHttp 3 and Jackson.
8+
9+
## Table of Contents
10+
11+
- [1. Project Overview](#1-project-overview)
12+
- [2. Features & Status](#2-features--status)
13+
- [3. Requirements & Compatibility](#3-requirements--compatibility)
14+
- [4. Architecture & Modules](#4-architecture--modules)
15+
- [5. Installation](#5-installation)
16+
- [6. Quick Start](#6-quick-start)
17+
- [7. Configuration](#7-configuration)
18+
- [8. Core Usage / API](#8-core-usage--api)
19+
- [9. Testing & Build](#9-testing--build)
20+
- [10. Versioning & Branches](#10-versioning--branches)
21+
- [11. Contributing & License](#11-contributing--license)
22+
23+
## 1. Project Overview
24+
25+
`faceplusplus-java-sdk` wraps the Face++ REST API (`/facepp/v3/*`, `/facepp/v1/skinanalyze*`) in a small template-style API: `FaceppTemplate` exposes typed operation groups, `FaceppFaceOperations` / `FaceppFacesetOperations` implement the calls over `FaceppOkHttp3Template` (OkHttp 3 + Jackson), and typed response classes model the API results.
26+
27+
| What it is | What it is not |
28+
|:---|:---|
29+
| A typed client for the Face++ face recognition API | A Spring Boot starter (no auto-configuration) |
30+
| Synchronous + async operation variants (face / faceset) | A face-detection implementation (images are sent to the Face++ cloud) |
31+
| URL / Base64 / file input for images | A general HTTP client framework |
32+
33+
Typical use cases:
34+
35+
| Use case | Operations |
36+
|:---|:---|
37+
| Face detection & analysis | `detectUrl/Base64/File`, `analyze` |
38+
| Face comparison | `compareUrl/Token/Base64/File` |
39+
| Face search in a faceset | `searchUrl/Token/Base64/File` |
40+
| Faceset management | `createFaceset`, `updateFaceset`, `getFacesetList`, `getFacesetByToken/OuterId`, `addFaceWithToken/OuterId`, `removeFaceByToken/OuterId`, `getFaceDetail` |
41+
| Skin analysis | `skinAnalyzeUrl/Base64/File` (basic / advanced / pro) |
42+
| Async batch face management | `FaceppFaceAsyncOperations` / `FaceppFacesetAsyncOperations` |
43+
44+
**Project status:** active development.
45+
46+
## 2. Features & Status
47+
48+
| Feature | Status | Notes |
49+
|:---|:---|:---|
50+
| `FaceppTemplate` | Available | Entry point: `opsForFaceDetect()` / `opsForFaceset()` |
51+
| `FaceppFaceOperations` | Available | Detect / analyze / compare / search / skin-analyze with URL, Base64 or `File` input |
52+
| `FaceppFacesetOperations` | Available | Faceset CRUD, add/remove faces (token or outerId), face detail, set user id |
53+
| Async variants | Available | `FaceppFaceAsyncOperations`, `FaceppFacesetAsyncOperations` |
54+
| `FaceppOkHttp3Template` | Available | OkHttp 3 + Jackson HTTP layer: `post` / `get` / `doRequest` overloads, typed response mapping |
55+
| `FaceppProperties` | Available | Host, app credentials, OSS region, view size, token expiration (default 3600 s) |
56+
| Typed responses | Available | `FaceDetectResponse`, `FaceCompareResponse`, `FaceSearchResponse`, `Faceset*Response`, `FaceppResponse.isSuccess()`, ... |
57+
| Request options | Available | `FaceDetectOptions` (landmark, attributes, beauty score range), `FaceAnalyzeOptions`, `FaceSearchOptions`, `SkinAnalyzeOptions`, `FacesetBo` |
58+
| Unit tests | Not present | No test sources in the repository |
59+
| CI pipeline | Not configured | No CI workflow files in the repository |
60+
61+
## 3. Requirements & Compatibility
62+
63+
| Requirement | Version |
64+
|:---|:---|
65+
| JDK | 8 |
66+
| Maven | 3.0+ |
67+
| OkHttp | 4.9.3 |
68+
| Jackson | 2.17.2 (`jackson-databind`) |
69+
| Face++ API | Face++ v3 face API (`api-cn.faceplusplus.com`) |
70+
71+
### Version lines
72+
73+
| Branch | JDK | Version pattern |
74+
|:---|:---|:---|
75+
| `feature/1.0.x` | JDK 8 | `1.0.x.*` |
76+
| `feature/2.0.x` | JDK 17 | `2.0.x.*` |
77+
| `feature/3.0.x` | JDK 21 | `3.0.x.*` |
78+
79+
## 4. Architecture & Modules
80+
81+
```text
82+
Your code faceplusplus-java-sdk Face++ cloud
83+
--------- --------------------- ------------
84+
FaceppProperties -> FaceppTemplate
85+
|
86+
+--------------+--------------+
87+
| |
88+
FaceppFaceOperations FaceppFacesetOperations
89+
(+Async) (+Async)
90+
| |
91+
+------------> FaceppOkHttp3Template <------------+
92+
(OkHttp 3 + Jackson) |
93+
| |
94+
+--> POST /facepp/v3/* ---+
95+
(api-cn.faceplusplus.com)
96+
|
97+
v
98+
typed response classes (resp/*)
99+
```
100+
101+
Single module, jar packaging:
102+
103+
| Package | Responsibility |
104+
|:---|:---|
105+
| `com.faceplusplus.spring.boot` | `FaceppTemplate`, `FaceppProperties`, `FaceppOkHttp3Template`, operation classes, constants |
106+
| `com.faceplusplus.spring.boot.req` | Typed request options (`FaceDetectOptions`, `FacesetBo`, ...) |
107+
| `com.faceplusplus.spring.boot.resp` | Typed response models (`FaceppResponse` base, detect/compare/search/faceset responses, ...) |
108+
109+
## 5. Installation
110+
111+
### Maven
112+
113+
```xml
114+
<dependency>
115+
<groupId>io.github.easy4j</groupId>
116+
<artifactId>faceplusplus-java-sdk</artifactId>
117+
<version>2.0.x.x.20260630-SNAPSHOT</version>
118+
</dependency>
119+
```
120+
121+
### Gradle
122+
123+
```groovy
124+
implementation 'io.github.easy4j:faceplusplus-java-sdk:2.0.x.x.20260630-SNAPSHOT'
125+
```
126+
127+
**Availability:** the artifact is published to the Aliyun private Maven repository and distributed through GitHub Releases; it has not yet been published to Maven Central.
128+
129+
## 6. Quick Start
130+
131+
```java
132+
import com.faceplusplus.spring.boot.FaceppOkHttp3Template;
133+
import com.faceplusplus.spring.boot.FaceppProperties;
134+
import com.faceplusplus.spring.boot.FaceppTemplate;
135+
import com.faceplusplus.spring.boot.req.FaceDetectOptions;
136+
import com.faceplusplus.spring.boot.resp.FaceDetectResponse;
137+
import com.fasterxml.jackson.databind.ObjectMapper;
138+
import okhttp3.OkHttpClient;
139+
140+
FaceppProperties properties = new FaceppProperties();
141+
properties.setAppId("your-app-id");
142+
properties.setAppCertificate("your-api-key");
143+
144+
FaceppOkHttp3Template http = new FaceppOkHttp3Template(new OkHttpClient(), new ObjectMapper(), properties);
145+
FaceppTemplate template = new FaceppTemplate(http, properties);
146+
147+
FaceDetectOptions options = FaceDetectOptions.builder()
148+
.returnLandmark(1)
149+
.returnAttributes("gender,age")
150+
.build();
151+
152+
FaceDetectResponse response = template.opsForFaceDetect()
153+
.detectUrl("https://example.com/face.jpg", options);
154+
155+
System.out.println("success=" + response.isSuccess());
156+
System.out.println("faces=" + response.getFaces());
157+
```
158+
159+
Expected result: the detected faces (with landmarks/attributes when requested) are returned in the typed `FaceDetectResponse`; `isSuccess()` reflects the Face++ `error_message`/`code` contract.
160+
161+
## 7. Configuration
162+
163+
Configuration is held in `FaceppProperties`:
164+
165+
| Property | Default | Description |
166+
|:---|:---|:---|
167+
| `host` | `https://api-cn.faceplusplus.com` | API base URL |
168+
| `appId` | — | Face++ API Key |
169+
| `appCertificate` | — | Face++ API Secret |
170+
| `expirationTimeInSeconds` | `3600` | Token expiration (seconds) |
171+
| `loginKey` / `loginSecret` | — | Login credentials (optional) |
172+
| `ossRegion` | — | OSS region for cloud storage (optional) |
173+
| `viewWidth` / `viewHeight` | — | View size (optional) |
174+
175+
Credentials are supplied by the application; keep them out of source control.
176+
177+
## 8. Core Usage / API
178+
179+
### 8.1 Face operations
180+
181+
```java
182+
// Detect from a local file
183+
FaceDetectResponse detect = template.opsForFaceDetect()
184+
.detectFile(new File("face.jpg"), options);
185+
186+
// Compare two images by URL
187+
FaceCompareResponse compare = template.opsForFaceDetect()
188+
.compareUrl("https://a.example/1.jpg", "https://b.example/2.jpg");
189+
190+
// Search within a faceset (by face token)
191+
FaceSearchResponse search = template.opsForFaceDetect()
192+
.searchToken(faceToken, FaceSearchOptions.builder().returnLandmark(1).build());
193+
```
194+
195+
### 8.2 Faceset operations
196+
197+
```java
198+
FacesetBo faceset = new FacesetBo();
199+
faceset.setDisplayName("test set");
200+
faceset.setOuterId("test_set");
201+
faceset.setTags("demo");
202+
203+
FacesetCreateResponse created = template.opsForFaceset().createFaceset(faceset);
204+
String facesetToken = created.getFacesetToken();
205+
206+
FaceAddResponse added = template.opsForFaceset()
207+
.addFaceWithToken(facesetToken, "faceToken1", "faceToken2");
208+
```
209+
210+
### 8.3 API endpoint coverage
211+
212+
| Face++ API | SDK method |
213+
|:---|:---|
214+
| `/facepp/v3/detect` | `detectUrl/Base64/File` |
215+
| `/facepp/v3/face/analyze` | `analyze(faceTokens, options)` |
216+
| `/facepp/v3/compare` | `compareUrl/Token/Base64/File` |
217+
| `/facepp/v3/search` | `searchUrl/Token/Base64/File` |
218+
| `/facepp/v3/faceset/create|update|delete` | `createFaceset` / `updateFaceset` / `deleteFaceset` |
219+
| `/facepp/v3/faceset/getfacesets|getdetail` | `getFacesetList` / `getFacesetByToken/OuterId` |
220+
| `/facepp/v3/faceset/addface|removeface` | `addFaceWithToken/OuterId`, `removeFaceByToken/OuterId` |
221+
| `/facepp/v3/face/setuserid|getdetail` | `createFace(faceToken, userId)` / `getFaceDetail(faceToken)` |
222+
| `/facepp/v3/faceset/async/addface|removeface`, `task_status` | Async faceset operations |
223+
| `/facepp/v1/skinanalyze(_advanced|_pro)` | `skinAnalyzeUrl/Base64/File` |
224+
225+
> **Assumption:** endpoint constants are maintained in `FaceppApiAddress`; verify the exact paths against the Face++ console documentation for your API version.
226+
227+
## 9. Testing & Build
228+
229+
```bash
230+
./mvnw clean verify # compile, run tests, generate coverage report
231+
./mvnw clean install # install into the local repository
232+
```
233+
234+
- The repository currently contains no test sources.
235+
- Coverage is measured with the JaCoCo Maven plugin (target: 90% line coverage, `haltOnFailure=false`).
236+
- The `release` profile assembles GPG signing + sources + Javadoc + deployment (`./mvnw -Prelease clean deploy`).
237+
238+
## 10. Versioning & Branches
239+
240+
Three parallel version lines are maintained:
241+
242+
| Branch | JDK | Version pattern |
243+
|:---|:---|:---|
244+
| `feature/1.0.x` | JDK 8 | `1.0.x.*` |
245+
| `feature/2.0.x` | JDK 17 | `2.0.x.*` |
246+
| `feature/3.0.x` | JDK 21 | `3.0.x.*` |
247+
248+
Maintenance strategy: the 1.0.x line receives bug fixes while JDK 8 remains the baseline; feature development primarily targets the 2.0.x / 3.0.x lines.
249+
250+
## 11. Contributing & License
251+
252+
Contributions are welcome — open an issue or submit a pull request against the matching version-line branch (`feature/2.0.x` for JDK 17 changes).
253+
254+
This project is licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). See the `LICENSE` file in the repository root for details.

0 commit comments

Comments
 (0)