From a7a5aec915852c06450f4a0c2b231cad72cf6aff Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Sun, 21 Jul 2024 14:08:45 +0800 Subject: [PATCH] doc: update README --- doc/DEV_HELP.md | 24 ++++---- doc/README.md | 149 ++++++++++++++++++++++++----------------------- doc/README_ZH.md | 137 ++++++++++++++++++++++--------------------- 3 files changed, 161 insertions(+), 149 deletions(-) diff --git a/doc/DEV_HELP.md b/doc/DEV_HELP.md index b68e4ae..9d7a473 100644 --- a/doc/DEV_HELP.md +++ b/doc/DEV_HELP.md @@ -1,19 +1,19 @@ -# Develop Help +# Developer Help -## Encoding System - -The core of this dumper, `obj_export.cpp` use different encoding processing strategy with the operating system due to some feature implementations. There are the detail of this core's mechanism. +## Basic Steps -Virtools use multibyte encoding system related to current system. Stored CKObject name is rely on document's author's encoding(code page). +1. First we create an instance of `ExportSettingDialog`, open a dialog and order user input export settings. Dialog read config manager settings when loading, and save settings to config manager after user click OK and input has been validated. +1. Fetch `ExportSetting` from dialog, create `ExportLayoutWeaver` instance and send into it. `ExportLayoutWeaver` will collect all 3D objects, meshes, materials and textures exported and give them an unique name according to `ExportSetting`. +1. Create `ObjExport` instance and fetch collected infomations in `ExportLayoutWeaver` to do read export. `ObjExport` will create essential files and write `ExportLayoutWeaver` collected infomations into it. -For model name, we call `CKObject.GetName()` first, then do some operations(name prefix and eliminating non-ASCII char) without considering this name's encoding(`obj_export::GenCKObjectName` done). Then, processed value will be delivered to `obj_export::GenObjMtlName` to generate the name which will be written in file with proper encoding. Also, this value will be transported to `obj_export::OpenObjMtlFile` which convert value into `wchar_t` type and opening corresponding model files via `_wfopen`. +## Encoding System -For texture file path, `obj_export::GenCKTextureName` generated the filename of texture file with `wchar_t` type first. Then `GenCKTextureName4File` generated filename used in model files. `CopyTextureFile` also use returned value to saving texture file. The detail is that call `CKTexture.SaveImage()` first and save texture file with proper file suffix(due to Virtools use file extension name to recognize the format of saved files) into temp folder. Then call `MoveFileW` and use `wchar_t` path value to move it into correct path. The reason why use this non-straight method is that `CKTexture.SaveImage()` do not support UTF8 encoding and also do not support `wchar_t` path. So we need a pure ASCII path to prevent any encoding problem. +The object name encoding convertion is located in `ExportLayoutWeaver`. Virtools use multibyte encoding system related to current system. Stored CKObject name is rely on document's author's encoding (code page). However, the whole program use UTF8 as default encoding. Thus `ExportLayoutWeaver` will try to convert CKObject name encoded by multibyte encoding system, to UTF8 according to user given encoding strategy. -Custom Encoding configuration only provide a chance to user that allow exporter to read multibyte string with correct encoding, otherwise exporter will assume this multibyte string is based on current Windows code page and process it directly. If Virtools composition contain character which can not be decoded in current Windows code page, exporter will throw unhandled exception. This is the problem of user, not the exporter, because user do not select correct encoding. In code, we assume that user know what they are doing. +For texture file path, it is done in both `ExportLayoutWeaver` and `ObjExport`. First `ExportLayoutWeaver` will try get texture slot file name and convert it to UTF8 according to user given encoding. Then it is passed to `ObjExport`. In `ObjExport`, we firstly generate a ASCII-only name first (keep the same extension format). And use `CKTexture.SaveImage()` to save it in Windows Temp directory. The use Win32 function `MoveFileW` to move it from Windows Temp folder to destination directory and rename it to the actual texture name at the same time. The reason why use this non-straight method is that `CKTexture.SaveImage()` do not support UTF8 encoding and also do not support `wchar_t` path. So we need a pure ASCII path to prevent any encoding problem. -## Bump version +## Bump Version -* Dialog left-bottom corner version string -* About dialog in `vt_menu.cpp` -* Macro `APP_VERSION` in `config_manager.cpp` if config file structure has been changed when bumping version. +* Dialog left-bottom corner version string (all languages, current is English and Simplified Chinese). +* About dialog string in string table (also for all languages). +* Version indentifier passed to `YYCC::ConfigManager::CoreManager` constructor in `ConfigManager.cpp` if config file structure has been changed when bumping version. diff --git a/doc/README.md b/doc/README.md index f6aba2b..54e9ec3 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,124 +1,129 @@ # vtobjplugin -[中文文档](README_ZH.md) +Virtools Wavefront OBJ Export Plugin. -Virtools Obj Plugin. +An interface plugin of Virtools which allows you to export some models as Wavefront OBJ format. -An interface plugin of Virtools which allows you to export some models as `.obj` file. - -Support Virtools 3.5, 4.0 and 5.0 +Support Virtools 3.0, 3.5, 4.0 and 5.0 ## Features ### Advantages -* Can omit world matrix (better than vt2obj. Omiting world matrix will omit object's move, rotation and scale). -* Support Blender and 3ds Max's repostion script for placing object (Place each object with the correct status in 3d software when you omit world matrix) -* Better right-hand left-hand coordinate system conversion. (From fliping Z axis to swaping YZ axis. This is more suit for Blender and 3ds Max 3d system) -* More material export options -* Comparing with vt2obj, it support more Virtools versions. It is convenient for Ballance object operation. -* Support *one file per object*. It is convenient for exporting object component. +* Can ignore object transform (i.e. keep the origin of object. better than vt2obj. Ignoring object transform will keep the origin of object but remove translation, rotation and scale of object). +* Support Blender and 3ds Max's reposition script for placing object (Re-place each object with their original transforms in 3D software when you check Ignore Object Transform) +* Better right-hand left-hand coordinate system conversion (From fliping Z axis to swaping YZ axis. This is more suit for Blender and 3ds Max 3d system). +* More material export options. +* Comparing with vt2obj, it support more Virtools versions. It is convenient for Ballance and other games to export 3D objects. +* Support *One File per Object*. It is convenient for exporting object components. ### Shortcomings -* Right-hand left-hand coordinate system conversion only support swaping YZ axis. -* No smooth group -* Only export 3d object. Don't support 2 dimension structure such as Line and etc. +* Right-hand left-hand coordinate system conversion only supports swaping YZ axis. +* No smooth group. +* Only can export 3D object. Doesn't support 2D structure such as Line and etc. ## Usage -1. Put plugin dll into Virtools's `InterfacePlugins` folder +1. Put downloaded plugin DLL into Virtools's `InterfacePlugins` folder 1. Launch Virtools and open the document which you want to export objects from. -1. According to your need, considering whether you need do some extra operations. -1. Click menu`Vtobj`-`Export object`。 -1. Set all options in dialog and click OK to export objects. +1. Click menu`Wavefront OBJ`-`Export Objects`。 +1. Set proper settings in dialog and click OK to export objects. + +## Export Settings Manual + +### General Settings -## Export config description +* Export Mode: `An Object`, `A Group`, `Selected Objects` and `All`. For `An Object` and `A Group`, you should pick an item in following Combobox to export. +* File Mode: `All Objects in One File` and `One File per Object`. For the first option, file will be named as `all`. For the second option, file name is object name. This option only affect the count of OBJ and MTL files. +* Export Directory：It should be an existing folder. And you should pay attention to that the conflict file will be overwritten directly without any notification. -### General Setting +### Object Settings -* Export mode: `An object`, `A group` and `All`. For `An object` and `A group`, you should pick a item in following Combobox. -* File mode: `All objects in one file` and `One file per object`. For the first option, file will be named as `all`. For the second option, file name is object name. This option only affect obj and mtl files' count. -* Export folder：It should be a existed folder. And you should pay attention to that the conflict file will be overwritten directly. +* Split Object by: Use `g` (group statement) or `o` (object statement) to split different objects in one OBJ file. +* Ignore Object Transform: Check suggested. This option is only served for the compability with original `vt2obj`. +* Convert to Right Hand Coordinate System: Convert to Blender and 3ds Max's coordinate system. +* Add Name Prefix: Add an unique name prefix to try avoiding possible name conflict. +* Eliminate Non-ASCII Characters: Eliminate all non-ASCII characters in exported files, including object names and texture files. This may be useful in place where OBJ importer couldn't correctly process encoding. -### Object Setting +### Reposition Settings -* Split object by: Use `g` command(group) or `o` command(object) to split object. -* Omit object transform data: Suggest check. This option is only served for the compability with original `vt2obj`. -* Convert to right-hand coordinate system: Convert to Blender and 3ds Max's coordinate system. -* Add name prefix: Add a unique name prefix to avoid name conflict. -* Eliminate non-ASCII characters: Eliminate non-ASCII characters in exported files. This may be useful in the place where obj importer couldn't process encoding correctly. +If you haven't check `Ignore Object Transform` and `Convert to Right Hand Coordinate System`, this sector's options are disabled. -### Reposition Script +Repostion means that restore the original transform of objects, including translation, rotation and scale. -If you don't check `Omit object transform data` or `Convert to right-hand coordinate system`, this sector's options are disabled. +* Generate 3ds Max Reposition Script (3dsmax.ms) +* Generate Blender Reposition Script (blender.py) -Repostion means that restore object's original move, rotation and scale. +### Material Settings -* Generate 3ds Max script (3dsmax.ms) -* Generate Blender script (blender.py) +* Export Material: Whether exporting MTL files. If you don't check it, the following options will be disabled. +* Export Texture: Whether including texture in MTL files. If you don't check it, all textures of object' will be removed and only keep its color properties such as ambient, diffuse and etc, and following options will be disabled. +* Copy Texture File: Copy texture to your export folder. If you have existing texture folder, you can uncheck this option to reduce the usage of storages and IO operations. +* Custom Texture Format: If you check this and write a new extension name, all texture will be change to new extension name you given. Please you don't need to enter dot (`.`) at the beginning of this setting. -### Material Setting +### Encoding Settings -* Export mtl file: If you don't check it, the following options are disabled. -* Export texture map in mtl: If you don't check it, all object's texture will be omitted and only keep light effect, such as reflect rate. And following options are disabled. -* Copy texture file: Copy texture into your export folder. If you have existing texture folder, you can close this option to reduce the usage of storages and reduce useless IO operation. -* Custom texture map format: If you check this and write a new suffix, all texture will be change to new format. +* Composition Encoding (aka. code page) + - System: Use system default encoding. Choose this if you want exporter to keep the same behavior with vtobjplugin 1.x version. This option also is suggested to be checked when the Virtools document is not garbled. + - Custom: Give user a chance to let the exporter read the object names correctly. Virtools uses a system-dependent multibyte encoding. Therefore, when the author of the Virtools document and the reader (you) have different system encodings, and the author uses non-ASCII characters in the document, the document will appear garbled. For example, Ballance uses Western European encoding to encode `A01_Geländer_01`, then under some other encodings, there will be garbled characters. In this case, if you select this option and fill in `28591` ([Windows code page](https://docs.microsoft.com/en-us/windows/win32/intl/code-page-identifiers)), the characters in document can be read correctly and output correct exported files. +* Use UTF8 in Object and Material File: Use UTF8 encoding instead of system encoding in OBJ and MTL files. This and next setting are typically used along with Custom option of Composition Encoding setting. +* Use UTF8 in Script File: Use UTF8 encoding in reposition script files. -### Encoding +## Export Import Tips -* Composition encoding - - System: Use system default encoding(aka. code page). Choose this if you want exporter to keep the same behavior with it's 1.x version. This option also can also be selected when the document is not garbled. - - Custom: Give the user a chance to have the exporter read the object names correctly. Virtools uses a system-dependent multibyte encoding. Therefore, when the author of the Virtools document and the reader (you) have different system encodings, and the author uses non-ASCII characters in the document, the document will appear garbled. For example, Ballance uses Western European encoding to encode `A01_Geländer_01`, then under some other encodings, there will be garbled characters. In this case, if you select this option and fill in `28591` ([Windows code page](https://docs.microsoft.com/en-us/windows/win32/intl/code-page-identifiers)), the characters in document can be read correctly and output correct exported files. -* Use UTF8 in object file: Use UTF8 encoding instead of local encoding in obj and mtl files. This and the next are typically used with Custom Composition Encoding option. -* Use UTF8 in script file: Use UTF8 encoding in script files. +Since the encoding settings of exporter are complex, and the exported models are mainly used for importing in 3ds Max and Blender, There are export and import tips for 3ds Max and Blender respectively for your reference. -## Export tips +### Export -Since the export encoding options are more complicated, and the exported models are mainly used for import in 3ds Max and Blender, the export encoding settings applicable to the two softwares are introduced here. The settings here are based on the default settings (the initial settings when you first launch this plugin). Please keep default settings if the options are not written here. +The settings written in there are based on the default settings (you can click Reset button in dialog to get it). Please keep default settings if the options are not written here unless you know what are you doing. -### Blender +#### Blender -* Set Composition encoding, if needed -* Check Use UTF8 in object file -* Check Use UTF8 in script file -* Check Generate Blender script +* Set Composition Encoding if reuqired +* Check `Use UTF8 in Object and Material File` +* Check `Use UTF8 in Script File` +* Check `Generate Blender Reposition Script (blender.py)` -> Blender and Blender's obj export plugin assume that model and script file are written in UTF8 encoding. So the file needs to be output in UTF8 mode, and at the same time there is no need to eliminate non-ASCII characters as Blender can handle them correctly. +> Blender and Blender's OBJ importer assume that model and script file are written in UTF8 encoding. So the file needs to be output in UTF8 mode, and at the same time there is no need to eliminate non-ASCII characters as Blender can handle them correctly. -### 3ds Max +#### 3ds Max -* Set Composition encoding, if needed -* Check Use UTF8 in script file according to your requirements. View following notes for more detail -* Check Eliminate non-ASCII characters -* Check Generate 3ds Max script +* Set Composition Encoding if reuqired +* Check `Use UTF8 in Script File` according to your requirements. View following notes for more detail +* Check `Eliminate Non-ASCII Characters` +* Check `Generate 3ds Max Reposition Script (3dsmax.ms)` -> 3ds Max's default obj importer does not recognize non-ASCII characters and will converts them to `_`(underline). Therefore, the generated script does not match the name of the object inside the model file name, and an error occurs when executing the script. So we need to eliminate non-ASCII characters when exporting. At the same time, the MAXScript executor of the old version of 3ds Max can only recognize UTF8 documents with BOM. Any other files with different encoding will let script become garbled. So it needs to use UTF8 to output script files. +> 3ds Max's default OBJ importer does not recognize non-ASCII characters and will converts them to `_`(underline). Therefore, the generated script does not match the name of the object inside the model file name, and an error occurs when executing the script. So we need to eliminate non-ASCII characters when exporting. At the same time, the MAXScript executor of the old version of 3ds Max can only recognize UTF8 documents with BOM. Any other files with different encoding will let script become garbled. So it needs to use UTF8 to output script files. -> There are 2 different 3ds Max MAXScript executing strategy. If you want to use *MAXScript - Run script* to execute script, you should not check *Use UTF8 in script file*. However, if you want to use *MAXScript - Open script* to open script file first and use *Tools - Evaluate all* to execute script in opened window, you should check *Use UTF8 in script file* +> There are 2 different 3ds Max MAXScript executing strategy. If you want to use *MAXScript - Run script* to execute script, you should not check `Use UTF8 in Script File`. However, if you want to use *MAXScript - Open script* to open script file first and use *Tools - Evaluate all* to execute script in opened window, you should check `Use UTF8 in Script File` -## Import tips +### Import -There are some tips for importing obj files generated by this plugin in 3ds Max and Blender. Following tips is under suggested export setting (the settings introduced before) +Following tips are suit for OBJ and MTL files exported under suggested export setting (the settings introduced before). -### Blender +#### Blender * Choose Y forward, Z up (same as Blender default system) -* Check Image search -* Check Group in Split +* Check `Split by Group` or `Split by Object` according to your chosen object split mode. -For reposition, load script file `blender.py` in Scripting tab and run it. +For reposition script, load script file `blender.py` in Scripting tab and run it. -### 3ds Max +#### 3ds Max -* Do not check Flip YZ Axis -* For normals, select imported from file -* Check import material +* Do **NOT** check Flip YZ Axis +* For normals, select Imported from File +* Check Import Material For reposition, click *MAXScript-Run* script in menu. Select `3dsmax.ms` and run it, or, click *MAXScript - Open script* to open script file first and use *Tools - Evaluate all* to execute script in opened window. This is rely on your chosen solution said in Export Tips section. ## Build -This project has various configurations which corresponding with Virtools 3.5, 4.0 and 5.0. There are also 2 build mode Debug and Release for each individual Virtools versions. It need their corresponding Virtools SDK to build. +Before building this project, you should prepare essential libraries: + +* [YYCC](https://github.com/yyc12345/YYCCommonplace): A homemade library which vastly used by my personal project. +* Virtools SDK: Virtools SDK usually distributed with Virtools self. If your SDK is invididual from Virtools installation, please put it inside Virtools because this project refer it by the root directory of Virtools. + +Next, you should have Python 3 and execute command `python "script\setup_env.py" -p -y ` at the root direcotry of this project. `` in command should be replaced by the path to the root directory of Virtools. And `` in command should be replaced by the install path of YYCC library (it's CMake install path, not the repository self of YYCC. It means that you should build YYCC library first). This command will configure build environment. -You should change some macros located in `vtobjplugin.props` before building this plugin. The macro should be pointed to your Virtools root path(without slash). Then, you can open the project in Visual Studio and choose the proper configuration to build this plugin. +Then, you can open the project in Visual Studio and choose `Release` configuration to build this plugin. The built plugin will be placed in Virtools's `InterfacePlugins` folder automatically. diff --git a/doc/README_ZH.md b/doc/README_ZH.md index 97ed3b5..f0c5380 100644 --- a/doc/README_ZH.md +++ b/doc/README_ZH.md @@ -1,23 +1,21 @@ # vtobjplugin -[English document](README.md) +Virtools Wavefront OBJ导出插件 -Virtools Obj 插件 +一个Virtools界面插件，允许你以Wavefront OBJ格式导出一些模型。 -一个Virtools界面插件，允许你以OBJ格式导出一些模型。 - -支持Virtools 3.5，4.0和5.0 +支持Virtools 3.0，3.5，4.0和5.0 ## 特性 ### 优点 -* 可以选择忽略世界变换矩阵（较于vt2obj更优，消除世界变换矩阵即消除物体的移动，旋转和缩放变换）。 -* 支持Blender和3ds Max的重定位脚本，方便复位（在使用忽略世界变换矩阵后方便在编辑软件中重新放置各类模型）。 +* 可以选择忽略物体变换（即保持物体原点。较于vt2obj更优。忽略物体变换将保留物体原点，但会消除物体的平移、旋转和缩放）。 +* 支持Blender和3ds Max的重定位脚本，方便复位（在使用忽略物体变换后，方便在在3D软件中将每个物体按其原始变换重新放置到其正确状态） * 支持更好的左右手坐标转换（从翻转Z轴改为交换YZ轴，更加符合Blender和3ds Max的轴向）。 * 增加更多材质导出选项。 -* 较于vt2obj支持更多Virtools版本，方便导出。 -* 支持每个物体一个文件，非常适合素材导出。 +* 与vt2obj相比，支持更多Virtools版本。便于Ballance和其他游戏导出3D物体。 +* 支持 *一个物体一个文件*，非常适合素材导出。 ### 缺点 @@ -27,96 +25,105 @@ Virtools Obj 插件 ## 操作方法 -1. 将插件安装到Virtools的`InterfacePlugins`文件夹中。 +1. 将下载好的插件放置到Virtools的`InterfacePlugins`文件夹中。 1. 启动Virtools，加载需要导出的文档。 -1. 根据需要，考虑是否需要做额外操作，比如只想导出路面或者某些物体，需要把相关物体归到一个新组中，或者不做任何操作，例如导出单个物体或全部物体。 -1. 点击菜单栏Vtobj - Export object。 -1. 弹出窗口中配置好各类参数，点击OK即可导出 +1. 点击菜单栏`Wavefront OBJ - 导出物体`。 +1. 在弹出窗口中配置好导出参数，点击`好`即可导出。 + +## 导出设置说明 + +### 常规设置 -## 导出选项解释 +* 导出模式：`一个物体`，`一个组`，`选定物体`和`全部`。对于`一个物体`和`一个组`，需要再点击下面的下拉框选择需要导出的物体或组。 +* 文件模式：`所有物体一个文件`和`每个物体一个文件`。前者文件名将命名为`all`，后者文件名为物体名称。此选项仅影响OBJ和MTL文件的个数。 +* 导出目录：需要是一个已经存在的文件夹。导出中如若碰到同名文件会直接覆盖，需要注意。 -### General Setting +### 物体设置 -* Export mode：导出模式，从`An object`（单个物体），`A group`（一个组里的所有物体）和`All`（所有物体）中选择一个。其中前两个选项需要再点击下面的下拉框选择物体或组。 -* File mode：文件模式`All objects in one file`（所有物体在一个文件里）和`One file per object`（一个物体一个文件）。前者文件名将命名为`all`，后者文件名为物体名称。此选项只影响obj和mtl文件个数。 -* Export folder：导出文件夹，需要是已存在的文件夹。导出中如若碰到同名文件会直接覆盖，需要注意。 +* 拆分物体方式：决定是使用 `g`（组语句）还是 `o`（物体语句）来划分物体。 +* 忽略物体空间变换：议勾选。此选项仅仅是为了提供向vt2obj兼容的功能而存在。 +* 转换到右手坐标系：转为右手坐标系，特指Blender和3ds Max类型的右手坐标系。 +* 添加名称前缀：添加唯一的名称前缀，以尽量避免可能的名称冲突。 +* 移除非ASCII字符：移除导出文件中的所有非ASCII字符，包括对象名称和纹理文件。在一些OBJ导入器不能够正确处理编码的场合可能会有用。 -### Object Setting +### 重新放置设置 -* Split object by: 决定是使用`g`（Group）语句还是`o`（Object）语句来划分物体。 -* Omit object transform data：忽略世界变换矩阵，建议勾选。此选项仅仅是为了提供向vt2obj兼容的功能而存在。 -* Convert to right-hand coordinate system：转为右手坐标系，特指Blender和3ds Max类型的右手坐标系。 -* Add name prefix：增加唯一的名称前缀以规避名称冲突。 -* Eliminate non-ASCII characters：消除文本中的所有非ASCII字符，在一些不能够正确处理编码的场合可能会有用。 +如果你没有勾选`忽略物体空间变换`和`转换到右手坐标系`，那么下述两项将不可用。 -### Reposition Script +重新放置意味着恢复物体的原始变换，包括平移、旋转和缩放。 -如果`Object Setting`中`Omit object transform data`和`Convert to right-hand coordinate system`中的任意一项不勾选，那么下述两项将不可用。 +* 生成3ds Max重新放置脚本（3dsmax.ms） +* 生成Blender重新放置脚本（blender.py） -* Generate 3ds Max script (3dsmax.ms)：生成3ds Max的重定位脚本 -* Generate Blender script (blender.py)：生成Blender的重定位脚本 +### 材质设置 -### Material Setting +* 导出材质：是否导出MTL文件。如果不勾选，下述所有选项将被禁用。 +* 导出贴图：是否在MTL文件中包含贴图。如果不勾选，物体的所有纹理将被移除，只保留其颜色属性，如环境光、漫反射等，并且下述所有选项将被禁用。 +* 复制贴图文件：将导出的材质复制到输出目录，如果你已有材质文件列表，可以关闭此选项以节省空间和不必要的IO操作。 +* 自定义贴图格式：如果勾选此选项并输入新的扩展名，所有材质都将更改为您指定的新扩展名。不需要输入扩展名开头的点（`.`）。 -* Export mtl file：导出mtl文件，如果不勾选，那么下述所有选项将不可用。 -* Export texture map in mtl：在mtl中导出贴图文件，如果不需要贴图（即只保留光照等效果），可以不勾选。不勾选此选项下述所有选项将不可用。 -* Copy texture file：将导出材质复制到输出目录，如果你已有材质文件列表，可以关闭此选项以节省空间和不必要的IO操作。 -* Custom texture map format：自定义材质格式。目前由于SDK限制无法读取原有材质格式，如果不勾选并填入后缀那么保存的材质将不具有任何后缀名，这可能会在Windows 10以前的操作系统上引发错误。 +### 编码设置 -### Encoding +* 文档编码（又名：代码页） + - 系统：使用系统的编码，选择此项即保持与1.x版本的导出器相同的行为。在文档没有出现乱码的情况下，也可以选择此项。 + - 自定义：给予用户一个让导出器正确读取物体名称的机会。Virtools使用依赖于系统的多字节编码。因此当Virtools文档的作者与阅读者（你）的系统编码不相同，且作者恰好在文档中使用了非ASCII字符，那么文档将会出现乱码。例如，Ballance使用西欧编码编码了`A01_Geländer_01`，那么在一些其它编码下则会出现乱码，此时若选择此项并填入`28591`（[Windows代码页](https://docs.microsoft.com/en-us/windows/win32/intl/code-page-identifiers)）则可以正确读取字符并输出正确的文件。 +* 在物体和材质文件中使用UTF8：在OBJ和MTL文件中使用UTF8编码，而不是本机编码。此项与下一项通常与文档编码的自定义选项一起使用。 +* 在脚本文件中使用UTF8：在重新定位脚本文件中使用UTF8编码。 -* Composition encoding - - System：使用系统的编码，选择此项即保持与1.x版本的导出器相同的行为。在文档没有出现乱码的情况下，也可以选择此项。 - - Custom：给予用户一个让导出器正确读取物体名称的机会。Virtools使用依赖于系统的多字节编码。因此当Virtools文档的作者与阅读者（你）的系统编码不相同，且作者恰好在文档中使用了非ASCII字符，那么文档将会出现乱码。例如，Ballance使用西欧编码编码了`A01_Geländer_01`，那么在一些其它编码下则会出现乱码，此时若选择此项并填入`28591`（[Windows代码页](https://docs.microsoft.com/en-us/windows/win32/intl/code-page-identifiers)）则可以正确读取字符并输出正确的文件。 -* Use UTF8 in object file：在obj和mtl文件中使用UTF8编码，而不是本机编码。此项与下一项通常与自定义文档编码一起使用。 -* Use UTF8 in script file：在脚本文件中使用UTF8编码。 +## 导出导入技巧 -## 导出提示 +由于导出选项的编码部分比较复杂，并且导出的模型主要用于3ds Max以及Blender内的导入，因此在此处分别介绍适用于两个软件的导出设置中的编码部分的设置。 -由于导出选项的编码部分比较复杂，并且导出的模型主要用于3ds Max以及Blender内的导入，因此在此处分别介绍适用于两个软件的导出设置中的编码部分的设置。此处的设置是基于对默认设置（即第一次使用此插件时的设置）的修改，如果没有陈述，则保持默认设置。 +### 导出 -### Blender +此处的设置是基于默认设置（可以单击对话框中的重置为默认按钮来获取它）的修改，如果没有陈述，则保持默认设置，除非你知道你正在做什么。 -* 设置Composition encoding，如果需要 -* 勾选Use UTF8 in object file -* 勾选Use UTF8 in script file -* 勾选Generate Blender script +#### Blender -> Blender本身和Blender的obj导出插件默认物体文件和脚本文件是以UTF8进行呈现的。因此需要以UTF8模式输出文本，同时不需要消除非ASCII字符，因为Blender可以正确处理这些字符。 +* 设置文档编码，如果需要需要的话 +* 勾选`在物体和材质文件中使用UTF8` +* 勾选`在脚本文件中使用UTF8` +* 勾选`生成Blender重新放置脚本（blender.py）` -### 3ds Max +> Blender本身和Blender的OBJ导出插件默认物体文件和脚本文件是以UTF8进行呈现的。因此需要以UTF8模式输出文本，同时不需要消除非ASCII字符，因为Blender可以正确处理这些字符。 -* 设置Composition encoding，如果需要 -* Use UTF8 in script file，请根据情况勾选，详见之后的注释 -* 勾选Eliminate non-ASCII characters -* 勾选Generate 3ds Max script +#### 3ds Max -> 3ds Max的默认obj导入器不能识别非ASCII字符，会将其转换为下划线。所以导致生成的脚本和模型文件名内部物体的名称不匹配，进而在执行脚本时出错。因此我们需要在导出时就消除非ASCII字符。同时旧版本的3ds Max的脚本执行器只能识别带有BOM的UTF8文档并正确显示多语言文本，因此需要使用UTF8输出脚本文件。 +* 设置文档编码，如果需要需要的话 +* `在脚本文件中使用UTF8`请根据情况勾选，详见之后的注释 +* 勾选`移除非ASCII字符` +* 勾选`生成3ds Max重新放置脚本（3dsmax.ms）` -> 3ds Max的两个MAXScript执行方法具有不同的文件读取策略。如果您想使用 MAXScript-运行脚本 执行脚本，那么您不可以勾选Use UTF8 in script file。如果您想使用先 MAXScript-打开脚本，然后在窗口中使用 工具-计算所有 来运行脚本，则可以勾选这个选项。 +> 3ds Max的默认OBJ导入器不能识别非ASCII字符，会将其转换为下划线。所以导致生成的脚本和模型文件名内部物体的名称不匹配，进而在执行脚本时出错。因此我们需要在导出时就消除非ASCII字符。同时旧版本的3ds Max的脚本执行器只能识别带有BOM的UTF8文档并正确显示多语言文本，因此需要使用UTF8输出脚本文件。 -## 导入提示 +> 3ds Max的两个MAXScript执行方法具有不同的文件读取策略。如果您想使用 *MAXScript-运行脚本* 执行脚本，那么您不可以勾选`在脚本文件中使用UTF8`。如果您想使用先 *MAXScript-打开脚本*，然后在窗口中使用 *工具-计算所有* 来运行脚本，则可以勾选这个选项。 -此处就Blender和3ds Max导入做一些提示。此处的设置是以对默认设置（即按照上述导出提示使用此插件时的设置）为前提进行讲述的 +### 导入 -### Blender +以下提示适用于在建议的导出设置（之前介绍的设置）下导出的OBJ和MTL文件。 + +#### Blender * 坐标轴选择Y forward, Z up（即与Blender默认坐标轴设置一致） -* 勾选Image search -* Split勾选Group +* 根据你之前选择的物体分割模式，勾选`Split by Group`或`Split by Object` -重定位在Scripting界面加载`blender.py`并执行即可 +对于重定位脚本，在Scripting界面加载`blender.py`并执行即可 -### 3ds Max +#### 3ds Max -* 不要勾选翻转YZ轴 +* **不要** 勾选翻转YZ轴 * 法线从文件导入 * 勾选导入材质 -重定位在菜单栏选择 MAXScript-运行脚本，选择`3dsmax.ms`并执行即可，或先 MAXScript-打开脚本，然后在窗口中使用 工具-计算所有。根据您之前在导出提示中做出的选择。 +重定位在菜单栏选择 *MAXScript-运行脚本*，选择`3dsmax.ms`并执行即可，或先 *MAXScript-打开脚本*，然后在窗口中使用 *工具-计算所有*。根据您之前在导出提示中做出的决定进行选择。 ## 编译 -此项目有许多配置，分别对应Virtools 3.5，4.0和5.0三个版本以及他们各自的Debug和Release编译模式，需要各自的Virtools SDK才能编译。 +在构建此项目之前，您应该准备好必要的库： + +* [YYCC](https://github.com/yyc12345/YYCCommonplace)：一个我个人项目广泛使用的自制库。 +* Virtools SDK：Virtools SDK通常随Virtools本身一起发布。如果您的SDK与Virtools安装相互独立，请将其放入Virtools中，因为此项目通过Virtools根目录来引用SDK。 + +接下来，你需要有Python 3，然后在此项目的根目录中执行命令`python "script\setup_env.py" -p -y `。命令中的``应替换为Virtools根目录的路径。``应该替换为YYCC库的安装路径（指的是CMake的安装路径，而不是YYCC的存储库本身。这意味着你应该先构建YYCC库）。这条命令将配置编译环境。 -如果您需要编译此项目，请先修改`vtobjplugin.props`中的宏定义，将其指向您的Virtools根目录（不加斜杠），然后在Visual Studio中选择合适的配置进行编译。 +然后，你可以在Visual Studio中打开项目并选择`Release`配置来构建此插件。构建的插件将自动放置在Virtools的`InterfacePlugins`文件夹中。