windows-non-ascii-path-workarounds

name	windows-non-ascii-path-workarounds
description	Use when Windows PowerShell, Python, OpenCV, training, document, video, or packaging workflows fail because paths contain Chinese or other non-ASCII characters; covers garbled paths, FileNotFoundError on existing files, cv2.imread returning None, UnicodeEncodeError, and ASCII staging workarounds.

Windows Non-ASCII Path Workarounds

Core Workflow

1. Capture the exact failing path and error string.
2. Verify the path really exists before blaming encoding.
3. Check whether the path contains Chinese or other non-ASCII characters.
4. If the failure is path-sensitive, create an ASCII-only working copy inside the current workspace.
5. Rerun the failing operation against the ASCII copy.
6. Apply the library-specific workaround only after the existence check is clean.
7. Copy or rename the final artifact back to a user-friendly name only after the workflow succeeds.

Proven Fixes

• PowerShell command layer corrupts a path: use Copy-Item -LiteralPath <source> -Destination <ascii-path> -Force, then work from the ASCII copy.
• OpenCV cannot read an existing image: replace cv2.imread(path) with np.fromfile(path, dtype=np.uint8) plus cv2.imdecode(...).
• OpenCV cannot write to a Chinese path: use cv2.imencode(ext, image)[1].tofile(path).
• A script has hardcoded absolute paths: rebuild paths from Path(__file__).resolve().parent and use Path joins.
• A trainer reports a missing dataset that exists: move both dataset and YAML/config to an ASCII-only workspace and point the command at the ASCII config.
• Console output throws UnicodeEncodeError: set UTF-8 output explicitly, for example PYTHONIOENCODING=utf-8.
• A document or media library fails only on the original filename: stage the source as source.pptx, source.pdf, input.jpg, or another simple ASCII filename.

Decision Rules

• Treat non-ASCII paths as an early branch on Windows, not a late suspicion.
• Do not retry the same command repeatedly once paths show garbling or an existing file is reported missing.
• Separate two cases clearly: the file truly does not exist versus the library cannot open an existing file.
• Prefer local staging over broad system changes.
• Preserve the user's original filenames for final output when it matters, but keep processing paths simple.

Verification

• The original path exists, or the missing-path condition is reported accurately.
• The ASCII staging copy exists and has the expected file type.
• The rerun command uses the ASCII path, not the original failing path.
• The downstream artifact was verified in its native way, such as image dimensions, page count, slide count, model loader success, or archive entries.
• If a final file was renamed back to a user-facing name, that final file exists and opens or loads correctly.