Yamyam: 1版をインポートしました

2018-06-28T17:49:22Z

1版をインポートしました

2010年3月31日 (水) 22:39にwiki>Mindronesによる

2010-03-31T22:39:36Z

新規ページ

== General Script Functionality ==
{{version|2.41+}}
This section sets out functionality and standards for scripts to be included in Blender.

=== Python Version ===
Scripts distributed with Blender should be compatible with Python 2.3.

=== Script Context ===
Before a user executes a script they need to know what it is operating on.

This may be set in the name of the script (in the menu), its tooltip or the scripts user interface.

Contexts may include...
* '''Active Object''' (only ever 1 object)
: <source lang="python">obj = Blender.Scene.GetCurrent().getActiveObject()</source>
* '''Selection''' (Assumed to mean visible Selection of current scene)
: <source lang="python">scn = Blender.Scene.GetCurrent()<br>objects = [ob for ob in scn.getChildren() if ob.sel if ob.Layers & scn.Layers]</source>
: or...
: <source lang="python">objects = Blender.Object.GetSelected()</source>
* '''Scene''' All objects in the current scene
: <source lang="python">objects = Blender.Scene.GetCurrent().getChildren()</source>
* '''All Scenes''' (In unusual situations you may need to operate on all scenes)
: <source lang="python">objects = Blender.Object.Get()</source>

The context also needs to be set as to the type of data that is used. So if a script just operates on meshes, this needs to be stated. If no type is defined then the user will assume that its operating on objects/data of all types.

====Rationale====
The user needs to know what the script is modifying, especialy when the data that is affected may not be visible at the time the script runs.

The worst case is a script modifys data in hidden layers or another scene, the user saves over the older file and then discovers later that the hidden data has been modified and needs to be made again.

=== New Objects ===
Scripts that create new objects by importing, generation or working from the current selection must set all new objects selected and other objects unselected.

New objects must never conflict with or overwrite existing data. scripts that use object or data names need to work properly when objects with the same names already exist. (be wary of <source lang="python">NMesh.PutRaw</source>)

New objects must be...
* selected, unselecting all previously selected objects in the current scene.
* unique and not interfere with the existing data
* created in a visible layer

====Rationale====
This is ideal because the user knows that all resulting data from the script is selected and can deal with the new data straight away.

e.g. Move to another layer, remove an unwanted import, link to an empty scene or switch to local view to better see the newly created data.

It is also consistant with current duplicate functionality.

=== Scenes Context ===
Scripts, exporters specifically, need to only deal with the current scene unless otherwise specified.

The usual mistake is to use '''<source lang="python">Blender.Object.Get()</source>''' as a list of objects to export from.

This will export all scenes on-top of each other and may take a long time as well as giving the user a bad result.

Use '''<source lang="python">Blender.Scene.GetCurrent().getChildren()</source>''' instead, so that all objects are taken from the scene that the user is currently working on.

=== Progress ===
For scripts that could take more then 1 second, the user needs to know that the script is processing data and when the script is finished. Use <source lang="python">Blender.Window.WaitCursor(1/0)</source> to let the user know when the script is finished.

You can also use <source lang="python">Blender.Window.DrawProgressBar(0.0, 'progressText')</source>

=== Errors ===
Scripts should not cause python to raise errors.

Problems with the users data, should be detected and a useful error appear.

Error messages also need to say if they stop the script from completeing or just a warning.
e.g.:
<source lang="python">Blender.Draw.PupMenu('ERROR%t|Select a mesh as your active object. aborting.')</source>
or
<source lang="python">Blender.Draw.PupMenu('WARNING%t|No materials applied to some objects. continuing.')</source>

==== Exception Handling ====
Using try/except blocks to handle errors is a good Thing and should be encouraged.

Good exception handling can be used to make sure a script does not leave the Blender data in a half-finished or damaged state or to simply do general cleanup.

=== Documenting Scripts ===
Willian- Comment?

=== Security ===
Don't use <source lang="python">exec</source> on unknown data, ask before overwriting? - expand

== Import/Export API ==
Blender has a growing list of importers and exporters. Standardized function names allows us to use these scripts in a generic way.

The most obvious use for this is as a file format converter, Blender supports these formats:
* 3DS
* OpenFlight FLT
* dxf
* obj
* Softaimage XSI

With standards, we can have importers/exporters act in a predictable way for the user as well as making them automated from other python scripts.

Here is an initial draft for a importer exporter API as well as some examples.

=== File Naming ===
Files should start with either <source lang="python">import</source> or <source lang="python">export</source> then prefixed with the format they work with e.g.:<source lang="python">import_xsi.py</source> <source lang="python">import_obj.py</source>, <source lang="python">export_3ds.py</source>

=== loading and saving function names ===
To be used by external scripts, the script's own user interface, or the file selector. These scripts cannot contain any user interaction.

<source lang="python">True</source> or <source lang="python">False</source> are returned based on weather the operation was successfull.

These functions take 1 absolute path to a file and any number of optional keywords: '''<source lang="python">read(file, *keywords*)</source>''' or '''<source lang="python">write(file, *keywords*)</source>'''

e.g. <source lang="python">write(file, EXPORT_EDGES=False, EXPORT_NORMALS=False, EXPORT_MTL=True, EXPORT_COPY_IMAGES=False, EXPORT_APPLY_MODIFIERS=True):</source>

=== User interface (read_ui/write_ui) ===
This function handles all the user interation, and gathers the optional arguments to pass to read/write. UI Drawing, Calls to the FileSelector are set here.

This function should never be called from anywhere other then the script itself.

In most cases, <source lang="python">Blender.Window.Fileselector</source> will call this function and all it will take is the filename.

=== Optional keywords ===
These optional keyword arguments can be passed to read and write functions. Keywords are specific to that function and are used to set options as with the example above. The keywords all need to have a default set so that the functions are optional, and scripts act as expected without having to pass specific keywords. - In most cases scripts that call the importers and exporters will not set non-default parameters. However, this may be desirable under some conditions.

Options keywords may be...
* <source lang="python">IMPORT_AT_CURSOR</source> - Imports objects using the 3d cursor loaction for the 0/0/0 center.
* <source lang="python">IMPORT_INTO_NEW_SCENE</source> - Creates a scene for the imported data.
* <source lang="python">IMPORT_MATERIAL</source> - Creates materials for the imported file.
* <source lang="python">IMPORT_MESH_FGONS</source> - Imports faces with more then 4 verts as fgons.
...and for exporters...
* <source lang="python">EXPORT_SCENE</source> - Exports all objects in the scene, not just the selected, visible ones.
* <source lang="python">EXPORT_COPY_IMAGES</source> - Copys all images to the output dir of the exported file.
* <source lang="python">EXPORT_SCALE</source> - Scales the exported data by this factor.

=== File compatibility testing function, importer only (iscompat) ===
This function takes a pathname and returns <code>True/False</code> depending on whether the file at the given path can be imported, this can be used to see if an importer can import a given file. For basic testing the file suffix is enough.

e.g.: <source lang="python">return file.lower.endswith('.obj')</source>

=== Data Compatibility Constant ===
Every i/o scipt must have a variable called '''<source lang="python">__FORMAT_COMPATIBILITY__'''</source>, this is a list of standard names that define what kinds of data the script can read/write.

e.g. <source lang="python">__FORMAT_COMPATIBILITY__ = 'MESH', 'MESH_NAME', 'MESH_VERT', 'MESH_EDGE', 'MESH_FACE', 'MESH_MATERIAL', 'MATERIAL', 'MESH_TEXFACE'</source>

The rationale for having this variable is that an external script can load an importer & exporter, telling the user what data will be lost if a conversion is made.

As scripts are converted the list of names for supported data will be added to. since there is a lot of data that blender does not import/export to, once defined here, scripts will be expected to use these names.

=== Blender Context ===
At the time of writing, importers and exporters have no defined context. A context standard is needed so read and write can be called one after the other, converting the data, without losing objects in a hidden layer or through it being unselected.

Currently some scripts export only the active object <source lang="python">(Blender.Object.GetSelection()[0])</source> Other scripts export objects from all scenes at once - <source lang="python">Blender.Object.Get()</source> - Some scripts silently import over other meshes with existing names. <source lang="python">Blender.NMesh.PutRaw()</source>

The new standard will be to import and export the user selection. - That is...
* Importing replaces the selection in the current scene with a new set of selected objects in the visible layers.
* Exporting uses the current scenes visible selection as the data to export.
...In situations where a different context is required, an optional argument can be used to change the default context.

=== Code Layout ===
All importers and exporters must follow this structure, foobar is used inplace of a real format name.
<source lang="python">
#!BPY
"""
Name: 'FooBar Model (.fbr)...'
Blender: 232
Group: 'Import'
Tooltip: 'Import a foobar file.'
"""
__bpydoc__ = """\
Breif format description and any special notes.
"""

__FORMAT_COMPATIBILITY__ = 'MESH', 'MESH_VERT', 'MESH_FACE', 'MESH_MATERIAL'

import Blender # Imports are optional, import whatever needs importing here.

def iscompat(file): # Only for importers
return file.lower().endswith('.fbr')

def read(file, IMPORT_AT_CURSOR=False, IMPORT_SCALE=1.0, IMPORT_INTO_NEW_SCENE=False):
# open and import the file
return True # Import was a success
# This function can work however you like
# and should only be used by the script its self.
def read_ui(file):
# Gather user option via PupMenu's, PupInput's, PupBlocks
# or a Registered python user interface.

# User interface aborts and tells
# the user if the file isnt the right format.
if not iscompat(file): ...

# Importing can take some time,
#best give some visual feedback.
Blender.Window.WaitCursor(1)
time1 = Blender.sys.time()

# We know the file exists and is compatible, import it.
read(file, IMPORT_SOME_OPTION=True...)

Blender.Window.WaitCursor(0)
# Usefull for the user to know the time an operation takes.
print 'Foobar exported in %.4f sec.' % ( Blender.sys.time()-time1 )

# This "if" is used so that importing the
# module dosent run the import user interface.
if __name__ == '__main__':
Blender.Window.FileSelector(read_ui, 'Import FooBar', Blender.sys.makename(ext=".fbr"))
</source>

=== Accessing read/write from other scripts ===
One of the main goals is to make the importers and exporters accessable as modules. Here is an example if a script that imports and exports a file.
<source lang="python">
import import_xsi
import export_3ds
file= 'C:\\temp\\testfile.xsi'
outfile= 'C:\\temp\\testfile.3ds'
if import_xsi.iscompat(file):
retval= import_xsi.read(file)
if retval:
export_3ds.write(outfile)
else:
print 'File not written, error occured'
</source>

[[Category:Script]]

← 古い版	2018年6月28日 (木) 17:49時点における版
(相違点なし)

Dev:2.4/Py/Scripts/Guidelines/previous work - 版の履歴

Yamyam: 1版 をインポートしました

2010年3月31日 (水) 22:39にwiki>Mindronesによる

Yamyam: 1版をインポートしました