Home
[TODO: links to each section]
[TODO: a 10-second GIF of importing a mesh sequence]
Importing a mesh sequence is easy:
- Click File > Import > Mesh Sequence
- Navigate to the folder where your mesh sequence is stored
- Select your file type and adjust your import settings
- In the File Name box, provide the first few letters of the name of one of your mesh files
- Leave the Cache Mode set to Cached
- Click Select Folder and wait while your sequence is loaded
Once it’s finished loading, you’re done!
[TODO: a 15-second GIF of importing a streaming sequence]
If your sequence is very long or the individual mesh files are very large, you may need to import a Streaming Sequence. It’s not difficult but it requires a little more configuration:
- Follow the first four steps found in the Quick Start instructions
- Set the Cache Mode to Streaming
- Click Select Folder and wait while the first frame of your sequence is loaded
- Find Object Properties > Mesh Settings
- Select a Cache Size for your sequence (pick the largest number of meshes that will comfortably fit in memory)
Once you start playing the animation, Stop Motion OBJ will automatically load meshes as-needed and remove meshes from the cache to maintain the requested Cache Size. If the sequence has more frames than the scene, make sure to update the End frame.
To download the latest version, go to Releases and download the latest version. If you want the latest production-ready version, search for the release with the "Latest Release" tag. Otherwise, simply choose the most recent pre-production release. To download, click Assets > Stop-motion-OBJ-v2.1.x.zip.
See the official Blender instructions for installing a 3rd party add-on. You do not need to restart Blender after Stop Motion OBJ is installed.
Stop Motion OBJ imports all files in a folder that match a given filename prefix. At a minimum, you must provide the path to the folder where the mesh files are contained (by navigating to it in the File Browser), and a common prefix for all of the mesh files in the sequence. Once you’ve navigated to the correct folder and provided a valid File Name prefix , click Select Folder to import the sequence. Files are loaded in alphanumeric order and leading zeros are not necessary for correct file ordering.
Three file formats are supported: OBJ, STL, and PLY. Select the format of your sequence using the File Format drop-down menu. Format-specific import settings will appear for each format (see below). Transform Pre-orient the sequence by changing the Forward and Up axes. This does not transform the actual vertices, it just applies a rotation to the sequence object.
Provide the common prefix for the names of all the files in your sequence. For example, if your files are called “Frame0001.obj”, “Frame0002.obj”, and “Frame0003.obj”, then a File Name Prefix of “Frame”, “Fr”, or even “F” would be enough to match these files. However, if there were another file in the folder called “French.obj” and you don’t want to include it in the sequence, you must provide at least “Fra” as the File Name Prefix to exclude it.
A Cached sequence means that all files in the sequence will be pre-loaded and stored in memory. The meshes will also be saved as part of the .blend file. Because all of the meshes are in memory, switching from one frame to the next is relatively fast and 24, 30, or 60fps playback is possible for simple meshes. However, if the combined size of the files in the sequence is very large, Blender may run out of memory and crash before the sequence is loaded. Stop Motion OBJ does not check to see whether the mesh sequence will actually fit within your RAM. If importing your sequence as Cached fails, or if you already know that it’s too large to fit in RAM, try Streaming mode (see below).
A Streaming sequence will pre-load only the first mesh in the sequence. Subsequent meshes in the sequence will be loaded only as-needed. You can adjust the sequence Cache Size to keep more than one mesh in memory. Once the cache is full, meshes are removed from the cache to make room for new meshes. This is especially useful if the meshes in your sequence are very large or the sequence is very long (or both).
If Material per Frame is unchecked, the material from the first mesh is stored in the sequence, then copied to each of the remaining frames in the sequence. For example, if you import a sequence with no materials and would like to create a new material for the entire sequence, you should leave Material per Frame unchecked so that the material is applied to every mesh in the sequence.
If Material per Frame is checked, each mesh in the sequence retains its own distinct material. For example, you would want to use this option if you have a sequence of photogrammetry scan data, since each mesh likely has its own unique texture and UVs.
[TODO]
Select a file format from the drop-down menu. Each format has its own import settings which will be available based on the format you’ve selected. Stop Motion OBJ uses the built-in file importers that ship with Blender.
[TODO: all OBJ-specific import settings. Image search, smooth groups, lines, clamp size, split, split by object, split by group]
[TODO: I’m not sure we’re going to keep all of these; these are just all of the settings offered by the built-in OBJ importer. Some might not be compatible with the Stop Motion OBJ paradigm]
Scale, Scene Unit, and Facet Normals work exactly as they do in the built-in STL importer. See the official documentation for information about these features.
The built-in PLY importer offers no PLY-specific import settings so none are included in Stop Motion OBJ.
Once your mesh sequence is loaded, you can adjust many settings related to playback, shading, and caching. These settings are found by selecting the mesh sequence, clicking on Object Properties, then opening the Mesh Sequence panel.
Mesh sequence settings for a Cached Sequence:
]
Mesh sequence settings for a Streaming Sequence:
]
The frame on which to start the mesh sequence. For example, if you want your sequence to begin playing on frame 12, set Start Frame to 12.
Mode dictates how the sequence is played before and after the imported range of frames. There are four modes to choose from:
- “Blank” makes the object disappear before and after the sequence.
- “Extend” freezes the first and last frames of the mesh sequence.
- “Repeat” plays the sequence in an endless loop.
- “Bounce” plays the sequence forwards then backwards in an endless loop.
This allows you to adjust the playback speed of the sequence. This is especially useful for importing a sequence at one FPS, then rendering it at a different FPS. For example, if you have 15FPS Kinect scan data, but want to render it at 30FPS, then set the Speed to 0.5 (input FPS ÷ target FPS). Be aware that this doesn’t perform any interpolation; it’s either skipping frames or duplicating frames.
This section only applies to Streaming sequences.
The Cache Size (measured in number of meshes) dictates how many meshes should be stored in memory at any given time. If you advance to a frame that is not yet loaded, the mesh for that frame is loaded on the fly. However, if you switch to a frame that has already been cached, it will load more quickly. The Cache Size should be small enough that the entire cache can fit within your RAM. Be aware that it is your responsibility to ensure the Cache Size is not too large. Too large a Cache Size may still result in Blender running out of memory and crashing. Note: a Cache Size of 0 means that no meshes will be removed from the cache.
When Stream During Playback is checked, new meshes will be loaded as soon as you advance to a frame with an un-cached mesh.
If Stream During Playback is unchecked, Stop Motion OBJ will not load any new meshes into the cache and simply display the most recent mesh.
For example, if you have a sequence of 200 frames, but only need 24 frames to set up your materials, lighting, etc., then set the Cache Size to 24, load the first 24 frames, then uncheck Stream Meshes During Playback. Now, it will smoothly display the meshes in your cache and not abruptly pause to load new meshes. Note that this feature is disabled during rendering so that your final render includes the full mesh sequence.
By default, the Blender OBJ importer applies smooth shading to the mesh. Also, the STL and PLY importers apply flat shading to the mesh. The Smooth and Flat shading buttons set the shading mode for the entire sequence with one click.
Note: Batch Shading is only available for Cached sequences.
If you have imported a Cached sequence, then made changes to the underlying mesh files (for example, if you lengthened or shortened the sequence, or you made changes to any of the meshes), click this button to clear out the existing sequence and reload the entire sequence from disk.
Note: Reload From Disk is only available for Cached sequences. Besides, this functionality is implicitly part of Streaming sequences.
The Bake Sequence operator applies all playback settings to the sequence and converts the sequence into a group of objects with visibility keyframes. Once a mesh sequence is baked, the sequence no longer relies on Stop Motion OBJ to switch between meshes. This allows you to render a mesh sequence on a render farm or share a .blend file with someone who does not have Stop Motion OBJ installed.
Note: Mesh Sequence Baking is only available for Cached Sequences.
Because of an old design choice, if you delete a sequence object, only the currently-visible mesh will be deleted. The other cached meshes will remain in memory and in the .blend file, even after you save it. When you close and reopen your .blend file, Stop Motion OBJ will automatically detect and remove these remaining meshes. Click the Delete Sequence button If you would like to delete a sequence and clear out the cache immediately.
The version of the addon that was used to create the currently-selected sequence. Down the road, this may be helpful for investigating backwards-compatibility bugs. Please include the Sequence Version in any issues you report.
When rendering a mesh sequence (especially a Streaming sequence), make sure to lock the interface during rendering: Render > Lock Interface. This prevents Blender from crashing during rendering (most of the time). Also make sure to render to still frames instead of directly to videos so that you don’t lose progress if Blender crashes.
Note: This is not required when rendering from the command-line.
[TODO: this section] [TODO: choosing Relative Paths before the first save, then moving the .blend file before the second save]
This is a known issue and can be reduced (if not eliminated) by locking the interface during rendering (Render > Lock Interface). Other Blender addons experience a similar issue: https://github.com/rlguy/Blender-FLIP-Fluids/wiki/Scene-Troubleshooting#blender-often-crashes-suddenly-or-does-not-apply-transforms-while-rendering
Mesh sequence exporting is not officially supported. However, some users have had luck exporting to Alembic. See this BlenderArtists message that describes the workaround. Exporting to FBX has been requested many times. I’ve tried many things to get this working, with no luck so far. Once Unity supports FBX files with constant interpolation, we might be able to get this working finally.
Make sure that the Stream During Playback checkbox is checked.
Make sure to use the Delete Sequence button to delete a mesh sequence. If you forgot to do that, just save your .blend file, then close and reopen Blender. Once you reopen your .blend file, Stop Motion OBJ should clean up the extra data.
Try re-importing the mesh sequence and check the Material per Frame option.
I’m really sorry about that. Take a look at the BlenderArtists thread and the open issues to see if others have had the same problem. If not, please file a bug on the repository.