--- title: Images, editable projects and archives description: Image geometry and transparency, portable FileHop projects, render limitations and archive extraction. order: 6 --- # Images, editable projects and archives ## Image options and limitations `image_resize` supports dimensions, percentage or longest edge, re-encoding, quality/target KB and print DPI. It does not enlarge unless `allow_upscale` is enabled; enlargement is bounded to 4× and 100 megapixels. `image_edit` applies an ordered list at full resolution: geometry, filters, adjustments, borders, text, shapes and image/text watermarks. - **Pixels and DPI are different.** Changing print DPI does not by itself add detail. Set pixel dimensions for screen requirements and the appropriate print density for physical output. - **Contain, cover and exact resizing differ.** Contain retains the whole image, cover fills a box by cropping, and exact dimensions can distort proportions. Discover the selected tool's enum rather than borrowing another tool's labels. - **Transparency can be flattened.** For `convert` to JPEG/BMP/GIF, choose `background` (default white); do not promise continuous alpha in those outputs. Use PNG or another suitable alpha-capable target when transparency matters. - **Size targets need verification.** Inspect actual output bytes and any warnings. Target compression support differs by tool and format; do not assume HEIC accepts the JPEG/PNG/WebP target-size API. - **Input support exceeds edit/export support.** Camera RAW conversion can use the camera's embedded JPEG, rather than developing the sensor data. PSD conversion is a flattened representation rather than preservation of Photoshop layers. - **Fonts are operation-specific.** `image_edit` text uses bundled Inter with Latin, Greek and Cyrillic coverage; do not assume it covers every script. Inspect text rendering for the language in use. - **Multi-page or animated sources need an explicit decision.** Single-image processing can refuse a sequence rather than silently using only the first page/frame. For a multipage TIFF, choose the TIFF-to-TIFF resize/recompress route to retain all pages. High-depth TIFF conversion can refuse formats that would lose precision; use supported TIFF/PNG paths when depth matters. - **HEIC transparency and layers are separate.** Supported alpha can survive HEIC decoding for pixel edits. Layered sources can be refused where a pixel edit would silently discard image items; a successful preview alone does not establish a safe round trip. For layered work that should remain editable, use an `imageEditor` project and typed project edits rather than a sequence of flattened outputs. ## Portable editable projects A project directory contains `project.fhproject` and local assets. `.fhpkg` packages the project for transport. Read `filehop://project-guide` and the installed schema before creating content. 1. `project_create` starts a supported project kind; `project_migrate` imports existing `.iep`, `.vep`, `.dep` or `.dwb` projects without changing originals. 2. `project_inspect` returns stable IDs, manifest revision, dependency revision and resolved assets. Request an outline or pointer for large models, and `journal: true` to resume existing work. 3. Use typed `project_image_edit` or `project_video_edit` operations where available. Generic `project_update` supports atomic edits, `dry_run` and schema validation. Do not invent native editor JSON. 4. Render, inspect diagnostics and export with the inspected manifest **and dependency** revisions. An asset can change even when the manifest does not. `project_add_asset` copies a local asset into the project and returns its ID. Refer to asset IDs in content. Assets must remain inside the project and permitted folders. Full editors can discard unreferenced assets on their next save, so complete the reference before handing the project back. Basic image/PDF/video/data project kinds support headless export. Full `imageEditor` exports PNG/JPEG; full `videoEditor` exports MP4 with the editor's supported model. `dataEditor` export requires its native editor. Creating, inspecting or migrating a project does not imply every kind supports headless export. Image typed edits include text, shapes, images, grouping, geometry, styles, masks and retouching. Retouch coordinates refer to source photo pixels; warnings can identify 8-bit/sRGB/opaque behavior or missing red-eye. Locked objects refuse changes unless explicitly overridden through a supported option. Inspect the image view for target paths and the renderer's feature diagnostics. `project_render` provides a cached preview without changing the project; `project_export` creates a unique output. Unsupported export features are refused rather than silently omitted. A preview may report differences; read its diagnostics instead of assuming a preview proves export support. For green/blue-screen overlays, `project_video_edit` can set an existing video overlay's `chromaKey` using its `track` and `id`, with `key: {color, similarity, smoothness, spill}`. Use a `#RRGGBB` color, similarity 1–100 and smoothness/spill 0–100. `key: null` clears the effect. Locked items and non-video overlays are refused. Preview the affected range before export. Use `project_pack`/`project_unpack` to move work and referenced assets together. History and checkpoints are excluded from packages unless `include_history` is requested. Use journal, history, diff and revert tools to record meaningful milestones and decisions. ## Let a person review the working project live Open the actual `project.fhproject` in a running FileHop window through `desktop_tabs`, or organize it in a `desktop_sessions` task with source/working/output roles. A clean open editor refreshes after saved external updates; unsaved human edits stay intact and produce a conflict. Keep working source editable and show coherent saved steps as the agent proceeds. Session readiness can distinguish opening, loading and rendering, and record exactly which revision and surface were shown. Each tool operation has an activity record; projects also have a journal and revision history. See [live review, sessions and audit trails](/docs/human-review-sessions/) for the full workflow and the distinction between render evidence and human approval. ## Archives `archive_create` writes ZIP (optional AES-256), 7z (optional encryption), tar.gz, tar.bz2 or tar.zst, leaving sources intact. Password protection and metadata hiding differ by archive format; consult its schema. Inspect creation `warnings` and `skipped` as well as the output path: a new archive can omit entries it cannot safely include. Archive creation and extraction need not handle links symmetrically; extraction skips links rather than following them. `archive_list` inspects entries before extraction. `archive_extract` supports ZIP, 7z, RAR, tar variants, standalone compressed streams and supported disk images. Disk-image operations depend on platform/runtime availability; check the installed capabilities. Extraction creates a new uniquely named directory and does not merge into an existing one. Paths escaping the destination, links, devices and pipes are skipped and reported. Inspect `skipped` before describing an extraction as complete. Current extraction bounds are 100,000 entries and a size allowance of 200× the archive size, bounded between 256 MB and 20 GB. Listing a format does not guarantee every encrypted or damaged variant can be extracted. Treat passwords, unsupported codecs and corrupt input as specific constraints instead of repeatedly trying different filename extensions.