add docs part 1
This commit is contained in:
+344
@@ -0,0 +1,344 @@
|
||||
# Search
|
||||
|
||||
This document describes the search functionality, including smart search, filters, and discovery features.
|
||||
|
||||
## Search Overview
|
||||
|
||||
The search feature allows users to find assets using:
|
||||
- AI-powered semantic search (CLIP)
|
||||
- Text-based search (filename, description, OCR)
|
||||
- Filter-based search (people, location, camera, date, type)
|
||||
|
||||
## Search Screen Layout
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ ← [ Search photos and videos... 🔍 ] [ ⋮ ] │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ [People] [Location] [Camera] [Date] [Type] [Display] → │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Search Results │
|
||||
│ or │
|
||||
│ Empty State │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Search Types
|
||||
|
||||
### 1. Context Search (AI/CLIP)
|
||||
- Default search mode
|
||||
- Uses AI to understand image content
|
||||
- Finds visually similar results
|
||||
|
||||
**Examples:**
|
||||
- "sunset on the beach"
|
||||
- "birthday cake"
|
||||
- "dog playing in park"
|
||||
- "red car"
|
||||
|
||||
### 2. Filename Search
|
||||
- Searches asset filenames
|
||||
- Partial matching supported
|
||||
|
||||
**Examples:**
|
||||
- "IMG_2024"
|
||||
- "screenshot"
|
||||
- ".png"
|
||||
|
||||
### 3. Description Search
|
||||
- Searches asset descriptions/captions
|
||||
- User-added metadata
|
||||
|
||||
### 4. OCR Search
|
||||
- Searches text detected in images
|
||||
- Useful for documents, signs, receipts
|
||||
|
||||
**Examples:**
|
||||
- "receipt"
|
||||
- "invoice"
|
||||
- Specific text in images
|
||||
|
||||
## Search API
|
||||
|
||||
### Main Search Endpoint
|
||||
```
|
||||
POST /search/smart
|
||||
|
||||
Body:
|
||||
{
|
||||
"query": "sunset beach",
|
||||
"page": 1,
|
||||
"size": 100,
|
||||
"type": "IMAGE" | "VIDEO" | null,
|
||||
"isFavorite": true | false | null,
|
||||
"isArchived": true | false | null,
|
||||
"takenAfter": "2024-01-01T00:00:00Z",
|
||||
"takenBefore": "2024-12-31T23:59:59Z",
|
||||
"city": "San Francisco",
|
||||
"state": "California",
|
||||
"country": "United States",
|
||||
"make": "Apple",
|
||||
"model": "iPhone 15 Pro",
|
||||
"personIds": ["person-uuid-1", "person-uuid-2"],
|
||||
"language": "en-US"
|
||||
}
|
||||
|
||||
Response:
|
||||
{
|
||||
"assets": {
|
||||
"items": [...],
|
||||
"nextPage": "2"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Search Suggestions
|
||||
```
|
||||
GET /search/suggestions?type={type}&country={country}&state={state}&make={make}&model={model}
|
||||
|
||||
Types: country, state, city, cameraMake, cameraModel
|
||||
```
|
||||
|
||||
## Filter Chips
|
||||
|
||||
### People Filter
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ People X │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Search people... │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
|
||||
│ │ 👤 │ │ 👤 │ │ 👤 │ │ 👤 │ │ 👤 │ │
|
||||
│ │ │ │ │ │ │ │ │ │ │ │
|
||||
│ │John │ │Jane │ │Bob │ │Alice│ │No │ │
|
||||
│ │ ✓ │ │ │ │ │ │ ✓ │ │Name │ │
|
||||
│ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │
|
||||
│ │
|
||||
│ [Clear] [Search] │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Location Filter
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Location X │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Country │
|
||||
│ [Select country... ▼] │
|
||||
│ │
|
||||
│ State │
|
||||
│ [Select state... ▼] │
|
||||
│ │
|
||||
│ City │
|
||||
│ [Select city... ▼] │
|
||||
│ │
|
||||
│ [Clear] [Search] │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Camera Filter
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Camera X │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Make │
|
||||
│ [Select camera make... ▼] │
|
||||
│ │
|
||||
│ Model │
|
||||
│ [Select camera model... ▼] │
|
||||
│ │
|
||||
│ [Clear] [Search] │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Date Filter
|
||||
Uses native date range picker:
|
||||
- Start date
|
||||
- End date
|
||||
- Presets: Today, This Week, This Month, This Year
|
||||
|
||||
### Media Type Filter
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Media Type X │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ○ All │
|
||||
│ ○ Images only │
|
||||
│ ○ Videos only │
|
||||
│ │
|
||||
│ [Clear] [Search] │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Display Options Filter
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Display Options X │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ☐ Not in any album │
|
||||
│ ☐ Archived only │
|
||||
│ ☐ Favorites only │
|
||||
│ │
|
||||
│ [Clear] [Search] │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Search Filter Model
|
||||
|
||||
```
|
||||
SearchFilter {
|
||||
// Text search
|
||||
context: String? // AI search query
|
||||
filename: String? // Filename search
|
||||
description: String? // Description search
|
||||
ocr: String? // OCR text search
|
||||
|
||||
// Filters
|
||||
people: Set<Person> // Selected people
|
||||
location: LocationFilter {
|
||||
country: String?
|
||||
state: String?
|
||||
city: String?
|
||||
}
|
||||
camera: CameraFilter {
|
||||
make: String?
|
||||
model: String?
|
||||
}
|
||||
date: DateFilter {
|
||||
takenAfter: DateTime?
|
||||
takenBefore: DateTime?
|
||||
}
|
||||
mediaType: AssetType // image, video, or other (all)
|
||||
display: DisplayFilter {
|
||||
isNotInAlbum: Boolean
|
||||
isArchive: Boolean
|
||||
isFavorite: Boolean
|
||||
}
|
||||
rating: RatingFilter // If rating feature enabled
|
||||
language: String // For AI search localization
|
||||
}
|
||||
```
|
||||
|
||||
## Quick Links (Empty State)
|
||||
|
||||
When search is empty, show quick access links:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ [Polaroid Image] │
|
||||
│ │
|
||||
│ Search photos and videos │
|
||||
│ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ 🕐 Recently Taken │ │
|
||||
│ ├─────────────────────────────────────────────────────┤ │
|
||||
│ │ ▶️ Videos │ │
|
||||
│ ├─────────────────────────────────────────────────────┤ │
|
||||
│ │ ♥️ Favorites │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Explore Data
|
||||
|
||||
### Explore API
|
||||
```
|
||||
GET /search/explore
|
||||
|
||||
Response:
|
||||
[
|
||||
{
|
||||
"fieldName": "exifInfo.city",
|
||||
"items": [
|
||||
{
|
||||
"value": "San Francisco",
|
||||
"data": { asset preview data }
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"fieldName": "smartInfo.objects",
|
||||
"items": [...]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Places / Map View
|
||||
|
||||
### Get Assets by City
|
||||
```
|
||||
GET /search/cities
|
||||
|
||||
Response: Array of assets grouped by city
|
||||
```
|
||||
|
||||
### Map Display
|
||||
- Shows assets as markers on map
|
||||
- Cluster markers for dense areas
|
||||
- Tap cluster to zoom or view assets
|
||||
- Filter by favorites, date range, partners
|
||||
|
||||
## People Search
|
||||
|
||||
### Get All People
|
||||
```
|
||||
GET /people
|
||||
|
||||
Response:
|
||||
[
|
||||
{
|
||||
"id": "person-uuid",
|
||||
"name": "John Doe",
|
||||
"birthDate": "1990-01-15",
|
||||
"thumbnailPath": "/path/to/thumb",
|
||||
"isHidden": false
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Person Detail
|
||||
```
|
||||
GET /people/{id}
|
||||
|
||||
Response:
|
||||
{
|
||||
"id": "person-uuid",
|
||||
"name": "John Doe",
|
||||
"birthDate": "1990-01-15",
|
||||
"thumbnailPath": "/path/to/thumb",
|
||||
"assets": [...]
|
||||
}
|
||||
```
|
||||
|
||||
## Pagination
|
||||
|
||||
- Search results are paginated
|
||||
- Initial page: 1
|
||||
- Load more on scroll to bottom
|
||||
- `nextPage` in response indicates more results
|
||||
|
||||
## Search Result Actions
|
||||
|
||||
Same as timeline multi-select:
|
||||
- Add to album
|
||||
- Favorite
|
||||
- Archive
|
||||
- Delete
|
||||
- Share
|
||||
- Download
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
1. **Debounced input**: Wait for user to stop typing
|
||||
2. **Cached suggestions**: Store frequently used
|
||||
3. **Incremental loading**: Paginate results
|
||||
4. **Cancel previous**: Cancel outdated requests
|
||||
|
||||
---
|
||||
|
||||
[Previous: Timeline & Photos](./timeline.md) | [Next: Albums](./albums.md)
|
||||
Reference in New Issue
Block a user