3dstojs

nodejs module to parse 3D Studio (.3ds) files to javascript and/or JSON

Usage no npm install needed!

<script type="module">
  import dstojs from 'https://cdn.skypack.dev/3dstojs';
</script>

README

3dstojs

A nodejs module to parses 3D Studio (.3ds) files to javascript or JSON.

Overview

Parse 3D Studio file (.3ds) to a javascript object or JSON.

Option to save the parsed data to a JSON file or break down the data to segments and save each segment to it's own JSON file (Materials, Objects/Mesh, Key Framer, etc...).

Due to .3ds file specifications not being public this parse does not parse everything in a .3ds file. To help with unknown chunks logs can be created during parsing and configured to capture unparseable to help update parsing ability.

Installation

npm install 3dstojs

Usage:

Returns a js object.

var parser = require("3dstojs");
var data = parser.parse("C:/3d/models/sample.3ds");

Returns a JSON string.

var parser = require("3dstojs");
var jsonStr = parser.parseToJson("C:/3d/models/sample.3ds");

Note: Both parse() and parseToJson() are synchronous calls

Methods

Parse - Takes in a filepath and optional options object. Returns a js objected of the parsed data. Options to save JSON and log information to a file. For options See below

parse(file, [options])

ParseToJson - Takes in a filepath and optional options. Returns a JSON string of the parsed data. Options to save JSON and log information to a file. For Options see below.

parseToJson(file, [options])

Help - Writes help text to the console. Same content as what is found in the "Options" section below.

help()

Parameters

These are the parameters for methods...

parse(file, options) and parseToJson(file, options)

file - - full path to the .3ds file."); options - - flags for events such as logging, saving to JSON files, etc...

Options

Is a js object that contains configurations for logging, saving JSON files, etc...

saveJson - bool (default: false) - flag to save parsed object to a JSON file.
saveOptions - object - Contains the following properties for saving to files (JSON, log, etc...)
 path - string (default: string directory of 3ds file.) - Location to save files.
 jsonPerItem - bool (default: false) - Save objects as separate JSON files.
 unparsedToFile - bool (default: false) - Saves the unparsable chunk to a file.
logging - bool (default: false) - Creates a log file of parsing events.
logOptions - object - Contains the follow flags on what is to be logged.
 read - bool (default: true) - Logs header chunks read from the file.
 parsing - bool (default: true) - Logs parsing of identifiable chunks.
 unparsed - bool (default: true) - Logs identifiable ids but not enough info to parse.
 unknown - bool (default: true) - Logs unknown chunk ids.
 jumping - bool (default: false) - Logs any position movement in the read file.
 files - bool (default: true) - Logs the json files saved to disk.
verbose - bool (default: false) - Prints the parsing progress and stats to the console.
verboseOptions - object - Contains the follow flags on what to write to the console.
 onlyStats: bool (default: false) - Shows only the stats on completion.
trackUnparsed - bool (default: false) - returns an object

Default Option object if the options parameter is omitted...

options = {
  saveJson: false,
  saveOptions:{
    path: '<directory of 3ds file>',
    jsonPerItem: false,
    unparsedToFile: false
  },
  logging: false,
  logOptions:{
    read: true,
    parsing: true,
    unparsed: true,
    unknown: true,
    jumping: false,
    files: true
  },
  verbose: false,
  verboseOptions:{
    onlyStats: false
  },
  trackUnparsed: false
}

Notes

Since the .3ds file format isn't publicly available this parser might not parse all data in your .3ds file. If you feel like not all of the data in the file was parse; use the options parameter to help figure out what chunks were not parsed.

The best option setup for unparsed/unkown chunks:

var options = {
  saveToJson: true,
  saveOptions: {
    unparsedToFile:true
  },
  logging: true,
  logOptions: {
    unparsed: true,
    unknown: true
  }
}

License

MIT