@harmonyos-arkts/d2h 0.0.0-stage → 0.1.0

package/skills/android2hmos_resources_convert/references/image-conversion-rules.md

@@ -0,0 +1,230 @@
+# Android to HarmonyOS Image Resource Conversion Rules
+
+Complete rules for converting Android **image resources** — bitmap files, nine-patch images, launcher icons (mipmap), adaptive icons — into HarmonyOS `media/` resources. XML drawables → SVG are covered separately in `xml-drawable-to-svg-rules.md`; this document defines what routes to SVG, plus the qualifier directory algorithm and reference resolution needed by image conversion.
+
+## Table of Contents
+1. [Target Directory Structure](#target-directory-structure)
+2. [Bitmap Images → media](#bitmap-images--media)
+3. [Nine-Patch Images](#nine-patch-images)
+4. [Mipmap → media](#mipmap--media)
+5. [Adaptive Icon → Layered-Image JSON](#adaptive-icon--layered-image-json)
+6. [Identifying XML vs Image Drawables](#identifying-xml-vs-image-drawables)
+7. [Qualifier Mapping](#qualifier-mapping)
+8. [Reference Resolution for Images](#reference-resolution-for-images)
+9. [Special Cases and Edge Cases](#special-cases-and-edge-cases)
+
+---
+
+## Target Directory Structure
+
+HarmonyOS image resources live under the `media/` resource group:
+
+```
+entry/src/main/resources/
+├── base/media/           # default images (no qualifier)
+├── ldpi/media/           # density-qualified
+├── dark/media/           # night mode
+├── zh_CN/media/          # locale-qualified
+└── zh_CN-dark-ldpi/media/  # combined qualifiers
+```
+
+HarmonyOS supported image formats: PNG, JPG, GIF, SVG, WEBP, BMP — all common Android bitmap formats copy directly.
+
+---
+
+## Bitmap Images → media
+
+Copy image files from Android `drawable*/` (and `mipmap*/`) to the qualifier-mapped `media/` directory:
+
+- `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp` → direct copy, filename unchanged
+- Resource names are preserved exactly as Android spells them — they are identifiers
+- Do NOT copy XML files in this step — classify them first (see [Identifying XML vs Image Drawables](#identifying-xml-vs-image-drawables))
+
+---
+
+## Nine-Patch Images
+
+Android nine-patch files (`.9.png`) have no native HarmonyOS equivalent:
+
+1. **Rename**: `.9.png` → `<name>_9.png`. HarmonyOS forbids `.` in resource filenames except the final extension separator, so `btn_bg.9.png` would be invalid — it becomes `btn_bg_9.png`.
+2. **Semantics lost**: the 1-px stretch/padding border markers are rendered as ordinary pixels; nine-patch stretching behavior does not carry over. The developer must implement stretching at the ArkUI component level (`.borderRadius` + `.resizable` or 9-slice via `ResizableOptions` where supported).
+3. Always log nine-patch conversions in the report with the rename and the lost-semantics note.
+
+---
+
+## Mipmap → media
+
+Launcher icons from `mipmap*/` directories go to the qualifier-mapped `media/` directory:
+
+- PNG/WEBP launcher icons (`ic_launcher.png`, `ic_launcher_round.png`, `ic_launcher_foreground.png`, `ic_launcher_background.png`, …) → direct copy
+- **Adaptive icon XML** (root `<adaptive-icon>`, commonly in `mipmap-anydpi-v26/`) → layered-image JSON (see below)
+- **VectorDrawable XML in mipmap** (root `<vector>`) → convert to SVG exactly like drawable vectors
+
+**Common pattern**: `mipmap-anydpi-v26/` is extremely common. Parse the qualifier as `anydpi` (→ `base`) + `v26` (→ strip) → target `base/media/`. Classify the files inside by their XML root element, never by the directory name.
+
+---
+
+## Adaptive Icon → Layered-Image JSON
+
+Convert `<adaptive-icon>` XML to `<original_name>_layered_image.json` in the target `media/` directory.
+
+**Conversion rules:**
+
+1. Parse the XML and extract the `<background>` and `<foreground>` elements.
+2. Only `background` and `foreground` are valid keys in the output JSON. Skip `monochrome` (and any other elements) **from the JSON output** — HarmonyOS layered-image has no equivalent. However, the resource *referenced* by `monochrome` is a real asset that must still be converted as a normal image.
+3. Convert references:
+   - `@drawable/xxx` → `$media:xxx`
+   - `@mipmap/xxx` → `$media:xxx`
+   - `@color/xxx` → **generate a solid-color PNG** (below) — layered-image only accepts `$media:` references, never `$color:`
+4. **Color background handling (critical)**:
+   a. Resolve `@color/xxx` to its hex value from `values*/colors.xml`, following reference chains to a concrete value.
+   b. Generate a solid-color PNG filled entirely with that hex (any small size, e.g. 1×1 or 108×108 px).
+   c. Save as `<color_name>_bg.png` in `base/media/`.
+   d. Reference it as `$media:<color_name>_bg` in the JSON.
+   e. If the color cannot be resolved (library resource, source `res/` fallback), log it as an unresolved dependency in the report.
+5. A layer may carry artwork as a **child element** instead of an `android:drawable` attribute (`<foreground><vector …/></foreground>`). Convert that inline drawable to its own media file named `<icon_name>_<layer>.svg` and reference it as `$media:<icon_name>_<layer>`. Never emit the JSON with the layer simply absent. A `<bitmap android:src="@drawable/x"/>` wrapper is just a reference — point at `$media:x`.
+
+**Example:**
+
+```xml
+<!-- mipmap-anydpi-v26/ic_launcher.xml -->
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/md_orange_700" />
+    <foreground android:drawable="@mipmap/ic_launcher_foreground" />
+    <monochrome android:drawable="@drawable/ic_launcher_monochrome" />
+</adaptive-icon>
+```
+
+Suppose `@color/md_orange_700` resolves to `#F57C00`. Generate `base/media/md_orange_700_bg.png` (solid `#F57C00`), then write `base/media/ic_launcher_layered_image.json`:
+
+```json
+{
+  "layered-image": {
+    "background": "$media:md_orange_700_bg",
+    "foreground": "$media:ic_launcher_foreground"
+  }
+}
+```
+
+`@drawable/ic_launcher_monochrome` is additionally converted as a normal drawable (SVG or bitmap per its type) even though it never appears in the JSON.
+
+---
+
+## Identifying XML vs Image Drawables
+
+In `drawable*/` and `mipmap*/` directories, classify every `.xml` file by its **root element** (never by filename or directory):
+
+| Root element | Type | Route |
+|---|---|---|
+| `<vector>` | VectorDrawable | → SVG (`xml-drawable-to-svg-rules.md`) |
+| `<shape>` | ShapeDrawable | → SVG |
+| `<layer-list>` | LayerListDrawable | → SVG |
+| `<selector>` | StateListDrawable | Extract default state → SVG; log dropped state variants |
+| `<adaptive-icon>` | Adaptive icon | → layered-image JSON (above) |
+| `<ripple>`, `<animated-vector>`, `<animated-selector>`, `<transition>`, `<level-list>`, `<scale>`, `<rotate>`, `<inset>` | Runtime behavior | Unmappable — log. Exception: `<inset>`/`<rotate>` with fixed values may be applied statically and the inner drawable converted; log either way |
+
+When several drawable directories provide the same resource name (`drawable/x.xml` and `drawable-anydpi/x.xml` both landing in `base/media/`), the source with **fewer qualifiers** wins; record the loser in the report as a collision — never silently drop it.
+
+---
+
+## Qualifier Mapping
+
+Android uses qualifier suffixes on resource directories; HarmonyOS uses a different qualifier naming scheme. Images are always placed under the `media/` group of the mapped qualifier directory.
+
+### Density Qualifiers
+
+The DPI range labels differ between platforms:
+
+| Android Qualifier | Approx DPI | HarmonyOS Qualifier | HarmonyOS DPI Range |
+|---|---|---|---|
+| `ldpi` | 120 | `sdpi` | (0, 120] |
+| `mdpi` | 160 | `mdpi` | (120, 160] |
+| `tvdpi` | 213 | `ldpi` | (160, 240] |
+| `hdpi` | 240 | `ldpi` | (160, 240] |
+| `xhdpi` | 320 | `xldpi` | (240, 320] |
+| `xxhdpi` | 480 | `xxldpi` | (320, 480] |
+| `xxxhdpi` | 640 | `xxxldpi` | (480, 640] |
+| `nodpi` | N/A | `base` | No density qualifier |
+| `anydpi` | N/A | `base` | No density qualifier |
+
+Note the deliberate mismatch: Android `hdpi` (~240) maps to HarmonyOS **`ldpi`** because HarmonyOS labels the (160, 240] range `ldpi`.
+
+### Language/Region Qualifiers
+
+| Android | HarmonyOS |
+|---|---|
+| `drawable-ar` | `ar/media/` |
+| `drawable-zh` | `zh/media/` |
+| `drawable-zh-rCN` | `zh_CN/media/` |
+| `drawable-zh-rTW` | `zh_TW/media/` |
+| `drawable-en-rUS` | `en_US/media/` |
+| `drawable-fr-rFR` | `fr_FR/media/` |
+
+Parsing: language = 2–3 lowercase letters (ISO 639); region = `r` + 2 uppercase letters, strip the `r`; script = `b+sr+Latn` → `sr_Latn`. Language and region join with `_`.
+
+### Orientation Qualifiers
+
+| Android | HarmonyOS |
+|---|---|
+| `land` | `horizontal` |
+| `port` | `vertical` |
+
+### Night Mode Qualifiers
+
+| Android | HarmonyOS |
+|---|---|
+| `night` | `dark` |
+| `notnight` | `light` |
+
+### Combining Multiple Qualifiers
+
+**Parsing algorithm for any Android drawable/mipmap directory name:**
+
+1. Split the directory name by `-`; the first segment is the resource type
+2. Parse remaining qualifiers left-to-right: language/region, density, orientation, night mode, API level (`v<N>`), screen-size constraints
+3. Map each recognized qualifier to its HarmonyOS equivalent
+4. **Strip silently** (do not reject): API level `v<N>`, layout direction (`ldrtl`/`ldltr`), screen shape (`round`/`notround`), HDR (`highdr`/`lowdr`), aspect (`long`/`notlong`)
+5. **Skip the entire directory** (mark all resources unmapped) when screen-size qualifiers remain: `sw<N>dp`, `w<N>dp`, `h<N>dp`, `small`, `normal`, `large`, `xlarge` — HarmonyOS has no equivalent; do NOT convert them to `base/`
+6. If no qualifiers remain after stripping, use `base/`
+7. Reassemble in HarmonyOS order: MCC_MNC-language_script_country/region-orientation-device-colormode-density
+
+**Examples:**
+
+| Android Directory | Qualifiers | HarmonyOS Target |
+|---|---|---|
+| `drawable-hdpi` | hdpi→ldpi | `ldpi/media/` |
+| `mipmap-anydpi-v26` | anydpi→base, v26 stripped | `base/media/` |
+| `drawable-zh-rCN-night-hdpi` | zh_CN, dark, ldpi | `zh_CN-dark-ldpi/media/` |
+| `drawable-night-v21` | dark, v21 stripped | `dark/media/` |
+| `drawable-hdpi-v4` | ldpi, v4 stripped | `ldpi/media/` |
+| `drawable-sw600dp` | **skip — unmapped** | N/A |
+
+Never reject a directory just because one qualifier is unsupported — strip it and continue.
+
+---
+
+## Reference Resolution for Images
+
+Image conversion encounters value references in three places. Build a lookup table from `values*/colors.xml` and `values*/dimens.xml` before converting drawables.
+
+**In converted SVG files:**
+- `@color/name` used as `fillColor`/`strokeColor` → resolve to the hex value during SVG generation (follow chains; fallback `#000000` + log)
+- `@dimen/name` used as a dimension → resolve to the numeric value (fallback: sensible default + log)
+- `@android:color/*` system colors → map known ones (`white`→`#FFFFFF`, `black`→`#000000`, `transparent`→`#00000000`); unknown → `#000000` + log
+
+**In layered-image JSON files:**
+- `@drawable/xxx` / `@mipmap/xxx` → keep as `$media:xxx` (file references — the files themselves are converted)
+- `@color/xxx` → resolve to hex and generate the solid-color PNG (see adaptive icon rules)
+
+**Reference chain depth**: follow at most 5 levels (`A → B → C → concrete value`). Unresolved references are expected — library resources are absent from source `res/`; record them in the report with likely library provenance (e.g. `@drawable/abc_*` → AndroidX AppCompat, `@drawable/mtrl_*`/`design_*` → Material Components) so the developer can supply them manually.
+
+---
+
+## Special Cases and Edge Cases
+
+- **Same name in multiple density directories** (`drawable-hdpi/x.png`, `drawable-xxhdpi/x.png`) → each copies to its own qualifier directory (`ldpi/media/x.png`, `xxldpi/media/x.png`) — no conflict.
+- **Same name from qualified and unqualified dirs** (`drawable/x.png` and `drawable-anydpi/x.xml` both → `base/media/`) → the source with fewer qualifiers wins; the loser is recorded as a collision.
+- **Existing files in the HarmonyOS project**: merge, do not overwrite — an existing media file with the same name keeps its position; the attempted copy is logged as a collision for the developer to review.
+- **Empty/corrupt image files**: skip and log; do not copy zero-byte files into `media/`.
+- **Filenames illegal in HarmonyOS** (`.` inside the name, leading digits are fine but uppercase is kept as-is): only the `.9.png` rename is automatic; any other illegal name is copied with a logged `unmappable` entry explaining the manual rename needed.
+- **Large image sets**: first inventory, then group by (classification × qualifier), then convert group by group, then verify — never convert while still scanning.

package/skills/android2hmos_resources_convert/references/svg-fix-patterns.md

@@ -0,0 +1,175 @@
+# SVG Display Issue Fix Patterns
+
+Common display abnormalities and fixes when migrating SVG/Vector Drawables from Android projects or manually creating SVGs.
+
+---
+
+## Issue 1: viewBox Does Not Match Path Coordinates
+
+### Symptoms
+Icon does not display at all, or only shows a blank area.
+
+### Cause
+The coordinate range defined by `viewBox` does not match the coordinate data in the `d` attribute of `<path>`.
+
+For example: path data is based on a 512×512 coordinate system (coordinate values range from 85 to 448), but `viewBox` is set to `0 0 24 24`, causing all paths to exceed the visible area.
+
+### Fix
+
+**Option A: Adjust viewBox to Match Path Coordinates (Recommended for Simple Cases)**
+```xml
+<!-- Wrong: viewBox too small -->
+<svg viewBox="0 0 24 24">
+  <path d="M101.51,411.23 Q85.21,395.05 ..." />  <!-- coordinates far exceed 24 -->
+</svg>
+
+<!-- Fixed: viewBox matches coordinate system, use width/height to control render size -->
+<svg width="24" height="24" viewBox="0 0 512 512">
+  <path d="M101.51,411.23 Q85.21,395.05 ..." />
+</svg>
+```
+
+> Note: `viewBox` defines the path coordinate space, while `width`/`height` define the render size. They are independent.
+
+**Option B: Scale Path Coordinates Proportionally (Recommended for Standardization)**
+
+Scale all values in the path proportionally to the target coordinate system. For example, scaling from 512 to 24:
+
+```python
+import re
+
+scale = 24.0 / 512.0  # 0.046875
+
+def scale_number(match):
+    num = float(match.group(0))
+    scaled = round(num * scale, 2)
+    return '{:.2f}'.format(scaled).rstrip('0').rstrip('.')
+
+path_data = "M101.51,411.23Q85.21,395.05 85.22,371.75..."
+result = re.sub(r'[0-9]+\.?[0-9]*', scale_number, path_data)
+```
+
+After scaling, you can use the standard `viewBox="0 0 24 24"`, consistent with other Material Design icons.
+
+---
+
+## Issue 2: Android Vector Drawable Syntax Remnants
+
+### Symptoms
+The SVG file contains Android-specific XML attributes that standard SVG renderers cannot parse.
+
+### Common Remnant Syntax
+
+| Android Syntax | Standard SVG Equivalent |
+|---------------|----------------------|
+| `<group android:translateX="24" android:rotation="90">` | `<g transform="translate(24,0) rotate(90)">` |
+| `android:fillColor="#FF000000"` | `fill="#000000"` |
+| `android:pathData="..."` | `d="..."` |
+| `android:viewportWidth="24"` | Part of `viewBox="0 0 24 24"` |
+| `<vector>` root element | `<svg>` root element |
+| `<clip-path android:pathData="..."/>` | `<defs><clipPath id="..."><path d="..."/></clipPath></defs>` |
+
+### Fix
+
+Fully convert Android `<group>` transform attributes to SVG `transform`:
+
+```xml
+<!-- Android Vector Drawable -->
+<group
+    android:translateX="24"
+    android:translateY="0"
+    android:rotation="90"
+    android:pivotX="12"
+    android:pivotY="12"
+    android:scaleX="1.5"
+    android:scaleY="1.5">
+  <path android:pathData="M18,12l4,-4..." android:fillColor="#FFFFFF"/>
+</group>
+
+<!-- Converted to Standard SVG -->
+<g transform="translate(24,0) rotate(90,12,12) scale(1.5,1.5)">
+  <path d="M18,12l4,-4..." fill="#FFFFFF"/>
+</g>
+```
+
+Transform order: `translate` → `rotate` (with pivot point) → `scale`
+
+---
+
+## Issue 3: Fill Color is White Causing Invisible Icon
+
+### Symptoms
+SVG file exists and path is correct, but icon does not display (invisible on white background).
+
+### Cause
+The original Android drawable's `fillColor` is `#FFFFFF` (white), which is invisible on a white background. Common for icons designed to appear on dark ActionBars.
+
+### Fix
+
+Change `fill="#FFFFFF"` to `fill="#000000"` (black), or choose a suitable color based on UI needs:
+
+```xml
+<!-- Before fix: white fill invisible on white background -->
+<path fill="#FFFFFF" d="M18,12l4,-4..."/>
+
+<!-- After fix -->
+<path fill="#000000" d="M18,12l4,-4..."/>
+```
+
+---
+
+## Issue 4: Google Material Symbols Coordinate System
+
+### Description
+Material Symbols SVGs downloaded from Google Fonts use a special coordinate system:
+
+```xml
+<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#000000">
+  <path d="M200-120q-33 0-56.5-23.5T120-200v-560..."/>
+</svg>
+```
+
+- `viewBox="0 -960 960 960"` — Y-axis starts at -960 (positive is upward)
+- Many negative values in path coordinates are normal
+- This format renders correctly in HarmonyOS, **no additional conversion needed**
+
+---
+
+## Issue 5: HarmonyOS media Directory Does Not Support Subdirectories
+
+### Symptoms
+Compilation error: `CompileResource` error "invalid path, not a file"
+
+### Cause
+Created subdirectories under `resources/base/media/` (e.g., `media/icons/`, `media/md/`).
+
+### Fix
+
+Move all files from subdirectories to the `media/` root directory, using file name prefixes to distinguish sources:
+
+```bash
+# Wrong: using subdirectories
+media/
+  md/
+    share.svg
+    home.svg
+
+# Correct: flat storage with prefixes
+media/
+  md_share.svg
+  md_home.svg
+  ic_custom_icon.svg
+```
+
+---
+
+## Quick Diagnosis Checklist
+
+When SVG icon does not display, check in order:
+
+1. **File exists?** — Confirm the file exists under `entry/src/main/resources/base/media/`
+2. **Reference correct?** — `$r('app.media.filename_without_extension')`, filename is case-sensitive
+3. **viewBox matches?** — `viewBox` coordinate range must cover path data coordinate values
+4. **Syntax standard?** — No `android:` namespace attributes, root element is `<svg>` not `<vector>`
+5. **Fill color visible?** — `fill` is not `#FFFFFF` (invisible on white background)
+6. **No subdirectories?** — SVG files are directly under `media/` root directory