GEM Importer

Руководство

GEM Importer преобразует входные файлы FBX, OBJ, glTF/GLB и MDL в набор GEM/MDL output-файлов.

Способы запуска программы:

1. Двойным щелчком по gem_import.exe. Программа работает согласно настройкам из конфигурационного файла gem_import.json.

2. Из командной строки. Этот способ позволяет передавать параметры для конкретного запуска программы без перезаписи конфигурационного файла gem_import.json.

Первый запуск

Первый запуск программы подразумевает, что в папке c gem_import.exe отсутствует конфигурационный файл gem_import.json.

При первом запуске GEM Importer создаёт базовый файл конфигурации gem_import.json в папке с gem_import.exe и завершает работу.

Первый запуск осуществляется двойным кликом по gem_import.exe или из командной строки без указания параметров [gem_import].

Импорт файлов во время первого запуска не выполняется.

Приоритет источников настроек

Итоговые значения параметров импорта формируются из трёх источников. Каждый следующий источник имеет более высокий приоритет и переопределяет соответствующие значения из предыдущего источника:

1. Встроенные значения по умолчанию;

2. Секции из gem_import.json;

3. Явные CLI-переопределения.

Параметры командной строки применяются только для текущего запуска и не изменяют содержимое gem_import.json.

Настройка gem_import.json

Файл gem_import.json является основным способом настройки GEM Importer. После первого запуска откройте созданный файл в текстовом редакторе и укажите параметры импорта. При последующих запусках двойным щелчком программа использует настройки из этого файла.

Пример gem_import.json

{
  "app": {
    "version": 2,
    "importer": "gem_import 1.0.0.110",
    "description": "Configuration for importing and exporting GEM/MDL assets",
    "author": "gem_import",
    "debug": {
      "outLog": "./out_log",
      "verbose": 1,
      "htmlFormat": false,
      "dryRun": false
    }
  },
  "import": {
    "general": {
      "inputDir": "./in",
      "outDir": "./out",
      "importUniformScale": 1.0
    },
    "content": {
      "volumes": true
    },
    "overwriteExisting": {
      "mesh": true,
      "texture": true,
      "animation": true,
      "material": true,
      "cmesh": true,
      "def": true,
      "mdl": true
    },
    "textures": {
      "searchPaths": [],
      "textureOutputSubdir": "",
      "useTexturesFromModel": true,
      "fileNameConvention": {
        "diffuse": ["basecolor", "base_color", "albedo", "diffuse"],
        "bump": ["normal", "normalmap", "normal_pbr", "bump", "nm"],
        "ao": ["ao", "ambientocclusion", "cavity"],
        "roughness": ["roughness", "rough", "rg"],
        "metallic": ["metallic", "metalness", "metal", "met", "mt"],
        "specular": ["specular", "spec", "sp"],
        "glossiness": ["gloss", "glossiness"],
        "emissive": ["emissive", "emission", "emit"],
        "fuzz": ["fuzz"]
      }
    },
    "materials": {
      "classSimple": "pbr/simple",
      "classStandard": "pbr/standard",
      "classStandardEmissive": "pbr/standard_emissive",
      "defaultNormal": "$/nmap_flat",
      "defaultAo": "$/white",
      "defaultRoughness": "$/white",
      "defaultMetallic": "$/black"
    }
  }
}

Таблица ключей gem_import.json

Секция	Ключ	Назначение
app.debug	outLog	Указание на папку логов
app.debug	verbose	Степень подробности файлового лога [0..2]
app.debug	htmlFormat	Записывать лог импорта в формате HTML, вместо TXT
app.debug	dryRun	Включает режим чтения/валидации без обычной записи результата
import.general	inputDir	Указание пути к исходной папке с файлами для импорта. Входные папки для --run-config
import.general	outDir	Указание пути к корневой папке результата импорта
import.general	importUniformScale	Задает scale для импортируемых моделей
import.content	volumes	Если выставлен, то импортер будет сохранять и экспортировать найденный volume/collision content в MDL и .cmesh
import.overwriteExisting	mesh, texture, animation, material, cmesh, def, mdl	Разрешение перезаписывать уже существующие output-файлы указанных типов
import.textures	searchPaths	Дополнительные папки поиска исходных текстур
import.textures	textureOutputSubdir	Относительная подпапка внутри outDir для экспортированных текстур. Если значение пустое, то текстуры будут писаться рядом с моделью
import.textures	useTexturesFromModel	true - брать texture-ссылки из source material; false - собирать material textures из папок, названных именами материалов
import.textures	fileNameConvention	Привязка суффиксов имён файлов к полям .material для режима useTexturesFromModel=false
import.materials	classSimple, classStandard, classStandardEmissive	Классы генерируемых MDL-materials
import.materials	defaultNormal, defaultAo, defaultRoughness, defaultMetallic	Fallback textures для генерируемых материалов

Обработка геометрии

Импортёр автоматически учитывает особенности систем координат входных форматов и выполняет преобразования, необходимые для GEM/MDL output. Для FBX и OBJ нормали генерируются только в том случае, если они отсутствуют в исходной модели.

Двухсторонность полигонов не настраивается через JSON.

• Для GLB/GLTF сохраняется doubleSided исходного материала.

• Для FBX учитываются material two-sided и явно заданный у узла CullingOff/CullingOn.

• Сабмеш без привязки к материалу принудительно получает twoSided=true.

Установка content.volumes=true не создаёт volumes из ничего. Флаг разрешает сохранить и записать volumes, которые importer распознал в исходной модели.

• При false volume-ресурсы и элементы .cmesh удаляются перед записью.

• Перезапись уже существующего .cmesh независимо контролируется через overwriteExisting.cmesh.

Флаг overwriteExisting

Флаги overwriteExisting не отключают экспорт нового файла. Они защищают только уже существующие файлы. Алгоритм отработки следующий:

• если файла ещё нет -> файл пишется;

• если файл уже есть -> файл пишется только при overwriteExisting.<type> = true.

Параметр необходим, чтобы не перезаписывать уже существующие и настроенные .def и .mdl файлы при повторном импорте модели.

Пример настроек секции overwriteExisting

"overwriteExisting": 
    { 
    "mesh": true, 
    "texture": true, 
    "animation": true, 
    "material": true, 
    "cmesh": true, 
    "def": false, 
    "mdl": false
    }

Обработка текстур

Значение параметра searchPaths задает путь поиска исходных текстур. Он используется в том числе для внешних картинок .gltf.

Значение параметра textureOutputSubdir задает output-подпапку для экспортированных текстур внутри outDir.

Тогда модель пишется в папку <outDir>/<model_stem>/, а текстуры пишутся в папку <outDir>/textures/<model_stem>/

Если textureOutputSubdir пустой, текстуры пишутся рядом с моделью.

Пример настройки секции textures

"textures": 
    { 
    "searchPaths": ["D:/SourceTextures/Rock"], 
    "textureOutputSubdir": "textures", 
    "useTexturesFromModel": true, 
    "fileNameConvention": 
        { 
        "diffuse": ["basecolor", "base_color", "albedo", "diffuse"], 
        "bump": ["normal", "normalmap", "normal_pbr", "bump", "nm"], 
        "ao": ["ao", "ambientocclusion", "cavity"], 
        "roughness": ["roughness", "rough", "rg"], 
        "metallic": ["metallic", "metalness", "metal", "met", "mt"], 
        "specular": ["specular", "spec", "sp"], 
        "glossiness": ["gloss", "glossiness"], 
        "emissive": ["emissive", "emission", "emit"], 
        "fuzz": ["fuzz"] 
        }
    }

Параметр useTexturesFromModel

1. Обычный режим (настройки по умолчанию):

"useTexturesFromModel": true

Importer берёт texture-ссылки из source material: FBX material slots, OBJ .mtl, или glTF/GLB materials.

1. Альтернативный режим:

"useTexturesFromModel": false

Importer игнорирует texture-ссылки внутри модели и ищет папки материалов рядом с исходной моделью, а также непосредственно внутри каждой папки из searchPaths.

Без searchPaths:

model_folder/
    model.fbx
    <materialName>/
        <anything>_<textureType>.<ext>

Если нужен дополнительный уровень textures, его надо явно указать относительно папки модели:

"searchPaths": ["textures"]

model_folder/
    model.fbx
    textures/
        <materialName>/
            <anything>_<textureType>.<ext>

Для абсолютного searchPaths используется та же схема:

<materialName>/
    <anything>_<textureType>.<ext>

Пример для material matid_1:

matid_1/
    rock_basecolor.jpg
    rock_normal.jpg
    rock_ao.jpg
    rock_roughness.jpg

Постфиксы типов настраиваются в секции import.textures.fileNameConvention:

"fileNameConvention": 
    { 
    "diffuse": ["basecolor", "base_color", "albedo", "diffuse"], 
    "bump": ["normal", "normalmap", "normal_pbr", "bump", "nm"],
    "ao": ["ao", "ambientocclusion", "cavity"],
    "roughness": ["roughness", "rough", "rg"],
    "metallic": ["metallic", "metalness", "metal", "met", "mt"],
    "specular": ["specular", "spec", "sp"],
    "glossiness": ["gloss", "glossiness"], 
    "emissive": ["emissive", "emission", "emit"],
    "fuzz": ["fuzz"]
    }

Ключом является поле/slot в генерируемом .material. Значение ключа представляет собой список допустимых суффиксов после последнего знака нижнего подчеркивания [ _ ] в имени файла. Имя непосредственной родительской папки должно совпадать с именем материала (файлы в папке другого материала игнорируются).

Импортёр сравнивает только часть имени после последнего знака нижнего подчеркивания [ _ ]. Поэтому составные значения со знаками нижнего подчеркивания, например base_color и normal_pbr, не распознаются. Используйте односоставные варианты basecolor, normal или normalmap.

В режиме useTexturesFromModel=false имена экспортированных .dds и ссылки на них внутри .material записываются в lowercase. Это обеспечивает точное совпадение путей на case-sensitive файловых системах, включая Linux.

Пример неправильной настройки параметра

Если в конфигурационном файле указано "bump": ["normal","normalmap","normal_pbr","bump","nm"],

то файлы

matid_1/rock_normal.png

и

matid_1/rock_normalmap.png

при импорте оба попадут в поле bump.

Параметры командной строки

Параметры командной строки позволяют изменить настройки для конкретного запуска GEM Importer. Переданные значения имеют приоритет над соответствующими значениями из gem_import.json, но не изменяют содержимое файла конфигурации.

Параметр	Назначение
Без параметров	Создать конфигурационный файл с базовыми настройками импорта gem_import.json и завершить работу (при первом запуске программы). Если gem_import.json существует, то запустить импорт файлов согласно настройкам конфигурационного файла
-i, --input <file>	Один входной файл. Поддерживаются форматы .fbx, .obj, .gltf, .glb, .mdl
--input-dir <dirs>	Одна или несколько входных папок; пути разделяются с помощью знака точки с запятой [ ; ]
--run-config	Импортировать из import.general.inputDir
-s, --settings <file>	Использовать указанный gem_import.json
-o, --out-dir <dir>	Корневая папка результата; переопределяет import.general.outDir
--verbose [0 | 1 | 2 ]	Задает уровень подробности лог-файла
--html --no-html	Писать HTML-лог Писать TXT-лог
--dry-run	Только чтение/валидация, без записи обычного результата
--write-help	Записать gem_import.md рядом с executable
--version	Показать версию gem_import и завершить работу
-h, --help	Показать консольную справку

Запуск с помощью BAT-файла

Для регулярного запуска GEM Importer с одинаковыми параметрами можно создать BAT-файл. Команду не потребуется вводить вручную при каждом запуске.

Создайте текстовый файл в папке с gem_import.exe, добавьте в него команду запуска и сохраните файл с расширением .bat, например import_models.bat:

@echo off
gem_import --input-dir "D:\Models\fbx;D:\Models\gltf" --out-dir "D:\Out" --verbose 1
pause

Для выполнения команды дважды щёлкните по созданному BAT-файлу. Команда pause оставляет окно командной строки открытым после завершения импорта, чтобы можно было проверить сообщения программы.

Примеры запуска из командной строки

Все приведённые ниже команды вводятся в командной строке Windows.

1. Импорт одного файла:

gem_import --input "D:\Models\vehicle.fbx" --out-dir "D:\Out" --verbose 2 --html

Команда импортирует файл vehicle.fbx, сохраняет результат в папку D:\Out и записывает расширенный лог в формате HTML.

1. Импорт файлов из нескольких папок:

gem_import --input-dir "D:\Models\fbx;D:\Models\gltf" --out-dir "D:\Out" --verbose 1

Команда импортирует поддерживаемые файлы из папок D:\Models\fbx и D:\Models\gltf. Пути к папкам разделяются точкой с запятой. Результат сохраняется в D:\Out, для файлового лога используется уровень подробности 1.

1. Импорт по указанному файлу конфигурации:

gem_import --run-config --settings "D:\Work\gem_import.json"

Команда использует файл D:\Work\gem_import.json и импортирует файлы из папок, указанных в import.general.inputDir.

Результат импорта (output files)

Типичным результатом импорта является набор файлов:

<outDir>/
    <model_stem>/
        <model_stem>.def
        <model_stem>.mdl
        .mesh
        .cmesh
        .material
        .animation
        *.dds

Набор файлов зависит от исходной модели и от того, есть ли соответствующие данные.