Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -181,11 +181,11 @@ To undo it, remove the entries in Windows Security → App & browser control →
| **Video**⁵: MP4, MOV, MKV, WEBM, AVI, WMV, FLV, MPEG, Video CD (DAT), TS, M2TS, 3GP, OGV, VOB, …;<br>Wisenet WAVE / Nx Witness exports (NOV) read | MP4 (H.264, HEVC, AV1), WEBM, MOV, MKV, AVI, GIF, APNG, MP3, M4A, 720p, split into parts;<br>subtitle tracks kept (MKV, MP4, MOV, WebM);<br>subtitles (SRT, ASS, WebVTT) |
| **Audio**⁵: MP3, M4A, AAC, WAV, FLAC, OGG, OPUS, WMA, AIFF, AMR, APE, WavPack, TTA, DSD (DSF, DFF), DTS, AC3, E-AC3, …;<br>tracker modules (XM, IT, S3M) read | MP3, M4A (AAC, ALAC), M4R (iPhone ringtone), WAV, FLAC, OGG, OPUS, AAC, WavPack, TTA, W64, AC3, E-AC3 |
| **Subtitles**: SRT, ASS/SSA, WebVTT, SAMI (SMI), LRC, KRC, TTML, MicroDVD, SCC | each other as UTF-8 (Korean CP949 files read correctly) |
| **Archives**: ZIP, ANSYS Workbench (WBPZ), 7Z, RAR, TAR, TAR.GZ, TAR.BZ2, TAR.XZ, GZ, ISO, CAB, DMG, ALZ, EGG, …;<br>JAR, NuGet (NUPKG), Android packages (APKS, XAPK, APKM, AAB), Adobe extensions (ZXP) read | extract, ZIP, 7Z, TAR, TAR.GZ;<br>any files → one ZIP; folders → ZIP, ISO (Joliet or UDF 2.01) |
| **Archives**: ZIP, ANSYS Workbench (WBPZ), 7Z, RAR, TAR, TAR.GZ, TAR.BZ2, TAR.XZ, GZ, ISO, CAB, DMG, ALZ, EGG, Garry's Mod addon (GMA), Valve pak (VPK), files packed into a Source map (BSP), …;<br>JAR, NuGet (NUPKG), Android packages (APKS, XAPK, APKM, AAB), Adobe extensions (ZXP) read | extract, ZIP, 7Z, TAR, TAR.GZ, GMA;<br>any files → one ZIP; folders → ZIP, ISO (Joliet or UDF 2.01), GMA |
| **CAD**: DWG, DXF<br>Gerber PCB layers (GBR, GTL, GBL, GTO, …) read;<br>G-code of 3D printers and CNC machines (GCODE, GCO, NGC) read | PDF, SVG, PNG, DWG ↔ DXF;<br>G-code → toolpath (from above or isometric) or the slicer's preview |
| **Fonts**: TTF, OTF, WOFF, WOFF2, EOT;<br>FON (Windows bitmap fonts) read | each other;<br>FON → one font per size |
| **Data**: JSON, JSON Lines, YAML, TOML, XML<br>vCard, iCalendar | each other, CSV and XLSX (tables);<br>vCard, iCalendar ↔ CSV |
| **3D models**: GLB, glTF, STL, OBJ (+ MTL), 3MF, PLY;<br>FBX read | each other, PNG preview |
| **3D models**: GLB, glTF, STL, OBJ (+ MTL), 3MF, PLY, studiomdl data (SMD);<br>FBX, Source engine model (MDL, with its VTF textures) read | each other, PNG preview |
| **Geospatial vectors**: Shapefile, GeoJSON, KML, KMZ, GPX<br>CSV with coordinates; Garmin FIT, OpenStreetMap (.osm) read | each other and CSV / XLSX / JSON;<br>projected data (UTM, Web Mercator, Lambert, Albers) comes out as WGS 84 longitude / latitude |

Unmarked formats work out of the box, without Office, Hancom Office or LibreOffice.
Expand Down
72 changes: 69 additions & 3 deletions docs/ENGINES.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Filee chooses engines automatically. Settings → *Engines* shows their status,
| Pictures to 3D relief | built in | **PNG, JPG, WEBP, … (every picture ImageMagick reads) → GLB, glTF, STL, OBJ, 3MF, PLY**: a relief, brighter areas higher |
| **Geospatial vector data** | built in | **GeoJSON, KML, KMZ, GPX, Shapefile ↔ each other and CSV** (longitude / latitude or WKT); Garmin FIT (activities) and OpenStreetMap XML (`.osm`), both read only, → each of them and CSV; projected Shapefiles (UTM, Web Mercator, Lambert, Albers) are converted to WGS 84; through CSV to XLSX, JSON, … (see below) |
| rhwp | bundled with the installer (`engines/rhwp`, with the Microsoft C++ runtime, see below) | HWP/HWPX → PDF, **HWP → HWPX, HWPX → HWP** |
| Archives (7-Zip) | bundled with the installer (`engines/7zip`, ~2.5 MB) + built-in readers | ZIP (including ANSYS Workbench WBPZ), 7Z, RAR, TAR (+ GZ/BZ2/XZ/Z/7Z/LZ), CAB, ISO, DMG, split (.001), Minecraft and Modrinth packs, … **→ folder, ZIP, 7Z, TAR, TAR.GZ/BZ2/XZ, the packs**; ALZ, EGG, lzip read in-process; "Compress into one archive" for any files |
| Archives (7-Zip) | bundled with the installer (`engines/7zip`, ~2.5 MB) + built-in readers | ZIP (including ANSYS Workbench WBPZ), 7Z, RAR, TAR (+ GZ/BZ2/XZ/Z/7Z/LZ), CAB, ISO, DMG, split (.001), Minecraft and Modrinth packs, Garry's Mod addons (GMA), Valve paks (VPK), the files packed into Source maps (BSP), … **→ folder, ZIP, 7Z, TAR, TAR.GZ/BZ2/XZ, the packs, GMA**; ALZ, EGG, lzip, GMA, VPK read in-process; "Compress into one archive" for any files |
| LibreOffice + H2Orestart + Java | **optional download** (~420 MB, 1.3 GB on disk) | older and rare formats only: DOC, XLS, PPT, RTF and OpenDocument → PDF and to each other, output as DOCX/ODT/ODS/ODP; HWP/HWPX → DOCX/ODT; read-only formats (see below) → PDF and their kind's editable formats; FODT, OpenDocument templates (OTT, OTS, OTP) and XLT out; SVG → EMF/WMF/ODG, a PDF page → SVG |
| Pandoc | **optional download** (~42 MB, 240 MB on disk) | Markdown ↔ DOCX/ODT/RTF, DOCX/ODT/HTML/RTF → Markdown, HTML ↔ DOCX/ODT, markup languages (reStructuredText, LaTeX, Org, AsciiDoc, Typst, MediaWiki, DocBook, Jupyter, Textile, man, OPML) ↔ Markdown/HTML/DOCX/ODT and each other (and → RTF, EPUB, TXT), Markdown and markup → PPTX slides |
| Ghostscript | **optional download** (~20 MB, 31 MB on disk) | EPS/PS → PDF, PDF → EPS/PS, PostScript-based AI → PDF (images through PDF and PDFium); smaller PDFs when a preset asks for it; PDF/A-2b for PDF/A presets; renders CMYK PDF/AI pages for CMYK JPG/TIFF |
Expand Down Expand Up @@ -1421,8 +1421,8 @@ to draw). G-code is a read-only CAD format (fields: 3D models and CAD).

## 3D models

`Filee.Engines/Models3D` converts GLB, glTF, STL, OBJ, 3MF and PLY into each other, and FBX into any of them, in
managed code: every reader
`Filee.Engines/Models3D` converts GLB, glTF, STL, OBJ, 3MF and PLY into each other, FBX and Source engine models (MDL)
into any of them, and studiomdl data (SMD) to and from them, in managed code: every reader
fills one in-memory model (`Model3D`: parts with positions, normals, UVs, vertex colours and triangles; materials
with a base colour and a base colour texture) and every writer takes it, so each pair is one step. glTF and GLB are
read and written with [SharpGLTF](https://github.com/vpenades/SharpGLTF) (MIT); STL, OBJ/MTL, PLY, 3MF and the FBX
Expand Down Expand Up @@ -1456,6 +1456,8 @@ What each format keeps:
| OBJ + MTL | `o` / `g` / `usemtl` as parts, `v` (+ r g b), `vt`, `vn`, faces of any size; `mtllib` with `Kd`, `d` / `Tr`, `map_Kd` (options skipped) next to the file | **the `.mtl` and the textures are written next to the `.obj`** (`name.obj`, `name.mtl`, `name_texture.png`, named like the output); vertex colours as `v x y z r g b` |
| 3MF | objects, components (also in other model parts, as Bambu Studio writes them), build transforms, base materials, colour groups (materials extension); `support` / `other` objects skipped | one object per part, base materials from material colours, a colour group from vertex colours |
| FBX (read only) | binary 6.x–7.x (64-bit records from 7.5, zlib-compressed arrays) and ASCII; mesh geometry with polygons of any size, the first normal, UV, colour and material layer (by polygon vertex, control point or polygon, or all the same; direct or indexed); the model hierarchy from the connections with translation, rotation (every Euler order, pre- / post-rotation, pivots and offsets), scaling and geometric transforms; property templates from Definitions; material `DiffuseColor` and `Opacity`; the diffuse texture embedded (Video `Content`) or named next to the file; animation, skins, blend shapes, NURBS, cameras and lights skipped (the rest pose is read) | — (not written) |
| SMD (studiomdl data) | the triangles of a reference SMD, one part per material (bones and weights not kept) | from an MDL: its bones, bind pose and weights (see below); from the others: a static prop with one root bone |
| MDL (Source engine, read only) | versions 44–49 with the `.vvd` and `.dx90.vtx` (else `.vtx`, `.dx80.vtx`, `.sw.vtx`) beside it (see below) | — (needs Valve's studiomdl) |
| PLY | ASCII, binary little / big endian; vertex position, normal, UV (`s`/`t`, `u`/`v`, `texture_u`/`texture_v`), colours of any type; face lists with per-corner `texcoord` and face colours; `comment TextureFile`; other elements skipped | binary little endian, one mesh; material colours become vertex colours |

Lost on the way (no place in the target): **STL** keeps only the triangles (no colours, UVs, normals or materials);
Expand All @@ -1470,6 +1472,35 @@ FBX's texture names) are read only from the model's folder or a folder below it.
points anywhere else is looked up by its name in the model's folder instead, so a downloaded model cannot pull a
picture from elsewhere on the disk into its output.

**Source engine models** (`.mdl`, #1526, the Games field; `Models3D/SourceModel.cs`): Garry's Mod, Counter-Strike:
Source, Team Fortress 2 and Half-Life 2 models are three files studiomdl writes side by side: the `.mdl` (bones,
textures, texture folders, the skin table, body parts → models → meshes), the `.vvd` (vertices with up to three bone
weights; fixups say which runs make LOD 0) and the `.dx90.vtx` (per mesh, strip groups of triangle lists or strips
indexing the mesh's vertices). All three must have the `.mdl`'s checksum, else the files belong to different builds and
the model is refused; a missing `.vvd` or `.vtx` is named. The model is read in its bind pose with its default body
groups (the first model of each body part), the first skin and LOD 0; animations, flexes, attachments and the physics
mesh (`.phy`) are not read. Source is Z up and measured in inches (25.4 mm), its triangles are clockwise and its UVs
start at the top left, so the model is turned to Filee's Y up, millimetres, counter-clockwise and bottom-left UVs; each
mesh becomes a part named after its model, with one material per texture. Later branches' 8-byte-longer strip groups
(CS:GO) are read when the indices of the usual layout don't fit.
The textures are found as Garry's Mod finds them: in the addon's or game's own layout, the `materials` folder beside the
`models` folder the model is in, `materials/<texture folder>/<texture>.vmt` for each of the model's texture folders
(`$cdmaterials`), letter case aside, then the material's `$basetexture` (also through a `patch` material's `include`) as
a `.vtf`, decoded by the VTF reader into a PNG texture; `$nocull` makes the material double-sided. Only `.vmt` and
`.vtf` files below that `materials` folder are read, never through `..`. A model outside such a layout, or one whose
materials come from the game itself (the HL2 textures), keeps plain materials. OBJ output writes the textures beside the
`.obj`, GLB embeds them.

**Studiomdl data** (`.smd`, #1526, the Games field; `Models3D/SmdFormat.cs`): the text Valve's studiomdl compiles models
from (`nodes`, a `skeleton` at `time 0`, `triangles`: a material line and three vertex lines of parent bone, position,
normal, UV and bone weights), Z up, in inches, counter-clockwise, UVs from the bottom left. An MDL becomes a reference
SMD as Crowbar decompiles it: its bones with their bind pose (position and rotation relative to the parent), its
triangles with up to three bone weights per vertex and the textures as materials, read straight from the model so the
skeleton is kept (Filee's own 3D model has no place for it). Any other model becomes a static prop: one `root` bone,
every vertex weighted to it, the material's (or texture's) name as the material line, normals computed where the model
has none. Reading takes the triangles of a reference SMD as a static model; an animation SMD (no triangles) is refused
with "no triangles", a broken line with its number. The "SMD" preset is in the palette, after glTF.

**3D → pictures**: a small software rasteriser (`MeshRenderer`) draws an isometric view from the front right, above,
with one light and flat shading per triangle, vertex colours or the texture interpolated across it, and a z-buffer,
at 2048 px and scaled down to 1024 px for smooth edges, on a transparent background. The preset's image options
Expand Down Expand Up @@ -1824,6 +1855,9 @@ bundled with the installer), never a 7-Zip installed on the PC. It runs as a sep
| Split archives (.001, .7z.001, .zip.001, .tar.001) | 7-Zip (combining .002, .003 … automatically) | — |
| ALZ (ALZip) | Filee: store, deflate and ALZip's bzip2 variant | — |
| EGG (ALZip) | Filee: store, deflate, bzip2, LZMA (decoded by 7-Zip); several blocks per file | — |
| GMA (Garry's Mod addon) | Filee: versions 1–3, CRCs checked, an `addon.json` written beside the files | Filee, as gmad does (see below) |
| BSP (Source engine map), its packed files | Filee copies the pakfile lump (a ZIP) out, 7-Zip unpacks it | — |
| VPK (Valve pak) | Filee: versions 1 and 2, `_dir.vpk` with its `_000.vpk` … parts, CRCs checked; a PS Vita `.vpk` (a ZIP) by 7-Zip | — |

- **Extract** (target `folder`): the archive is unpacked into a hidden folder next to the result and moved into place
when complete. When the archive holds exactly one top folder, its content becomes the result folder (`photos.zip`
Expand All @@ -1837,6 +1871,38 @@ bundled with the installer), never a 7-Zip installed on the PC. It runs as a sep
an archive or a folder whose only top folder holds the marker gets that folder's content, not the folder
(`GamePacks.Root`); an add-on (MCADDON, several packs side by side) is packed as it is. The presets (MCPACK …
MRPACK) are in the palette only.
- **Garry's Mod addons** (`.gma`, #1526, the Games field; `Archives/Gma.cs`, Filee's own reader): the Steam
Workshop's format, a header (title, a JSON description with the type and tags, author, timestamp), a file list
(names, sizes, CRC-32s) and the files one after another, ended by a CRC-32 of everything before it. Every name is
checked before anything is written (an absolute name, a drive or a `..` stops the addon), the entries are capped at
the archive limit and their sizes must fit inside the addon. Unpacking checks every file's CRC (0, as `gmad -nocrc`
writes it, is not checked) and writes an `addon.json` with the title, description, type and tags, so the folder packs
back into the same addon; the required-content list and the author are not kept (Garry's Mod uses neither). Packing
a folder, a ZIP of one or the files dropped onto "Compress into one archive" reads `addon.json` like gmad: `title`
(else the folder's name), `type` (else `servercontent`), `tags`, `description` and the `ignore` wildcards. Only
files on gmad's whitelist go in (`lua/*.lua`, `materials/*.vtf`, `models/*.mdl` …, the ones Garry's Mod mounts;
`addon.json`, `thumbs.db`, `desktop.ini`, `.git*` and `.DS_Store` never), so a `.psd` or a `readme.txt` beside them
is left out rather than failing the addon as gmad does without `-warninvalid`; a folder with none of them is
refused. Names are stored in lower case, sorted, with a CRC each. The type and tags are written as given (lower
case), not checked against the Workshop's lists. The "GMA" preset is in the palette after the game packs (schema
96), not on a donut.
- **Valve paks** (`.vpk`, #1526, the Games field; `Archives/Vpk.cs`): the archives Source engine games keep their files
in (`hl2_textures_dir.vpk`, the content Garry's Mod mounts). The directory file holds a tree of extensions, folders
and names; each file's content is a few preload bytes stored in the tree plus its data, which follows the tree in the
directory file (archive index 0x7FFF) or sits in `<name>_nnn.vpk` next to it. The directory file is what unpacks;
a data part on its own is refused with the name of its directory file, a missing part names the part. Every name is
checked before anything is written, the tree is capped at 256 MB and the entries at the archive limit, preload bytes
must lie inside the tree, parts are `_000` to `_999`, and each file's data must lie inside its part; the total is
checked against the free space first. The MD5 and signature sections of version 2 are not read; every file's CRC-32
is checked. Nothing writes VPK (Garry's Mod
loads addons as folders or GMA). A PS Vita package has the same extension but is a ZIP: it goes to 7-Zip.
- **Source engine maps** (`.bsp`, #1526, the Games field; `Archives/Bsp.cs`): the custom textures, models and sounds
packed into a map (by VBSP, VIDE or bspzip) are a ZIP stored as lump 40, the pakfile. Filee finds it in the lump
directory (offset, length, version, code; Left 4 Dead 2's version, offset, length order is used when only that one
points inside the file), copies it to the work folder and 7-Zip unpacks it, so a map extracts or converts to any
archive like one, with the same checks as any ZIP (names leaving the folder, the entry limit, the free space). The
lump must lie inside the map, and its copy is bounded by the lump's length. A map without packed files (an empty ZIP), a compressed pakfile lump and a Quake or GoldSrc map
(no `VBSP`) are refused with a message saying so. The map's geometry is not read.
- **Adobe extension packages** (`.zxp`, #1382, read only like JAR): the panels and plug-ins of After Effects, Premiere
Pro, Photoshop and the other Creative Cloud apps are signed ZIPs (`mimetype`, the extension's files and
`META-INF/signatures.xml`). They extract and convert to every archive target with the signature file inside.
Expand Down
4 changes: 2 additions & 2 deletions src/Filee.Core/Formats/FormatFields.cs
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ .. Enum.GetValues<FormatCategory>().Select(category => category.ToString().ToLow
"dts", "tar", "tgz", "tbz2", "txz", "tar7z", "tlz", "gz", "bz2", "xz", "lz", "lzma", "jar", "zxp", "nupkg", "apks",
"aab", "mcpack", "mcaddon", "mcworld", "mctemplate", "mrpack", "cab", "gerber",
"cpio", "deb", "rpm", "dwg", "ttf", "otf", "woff", "woff2", "ass", "ssa", "ttml", "scc", "glb", "gltf",
"stl", "obj", "3mf", "ply", "fbx", "gcode", "geojson", "kml", "kmz", "gpx", "shp", "fit", "osm", "xm", "it", "ani", "vtf"
"stl", "obj", "3mf", "ply", "fbx", "gcode", "geojson", "kml", "kmz", "gpx", "shp", "fit", "osm", "xm", "it", "ani", "vtf", "gma", "vpk", "bsp", "mdl", "smd"
]),
(FormatGrade.Legacy,
[
Expand All @@ -100,7 +100,7 @@ .. Enum.GetValues<FormatCategory>().Select(category => category.ToString().ToLow
// Layout, print, photo post-production, signs and embroidery.
(["psd", "psb", "exr", "hdr", "xcf", "kra", "pdn", "raw", "eps", "ps", "ai", "cdr", "plt", "dst"], ["design"]),
// Game textures and cutscenes, Minecraft packs and modpacks.
(["dds", "vtf", "usm", "bik", "mcpack", "mcaddon", "mcworld", "mctemplate", "mrpack"], ["game"]),
(["dds", "vtf", "usm", "bik", "mcpack", "mcaddon", "mcworld", "mctemplate", "mrpack", "gma", "vpk", "bsp", "mdl", "smd"], ["game"]),
// Medical imaging and astronomy.
(["dcm", "fits"], ["science"]),
// Software work: raw image formats of graphics tools, app icons and cursors, config and data files, flat XML
Expand Down
Loading
Loading