Upload 5 files

index.rst.txt

@@ -1,89 +1,17 @@
-.. _modifiers-index:
-.. _bpy.types.Modifier:
+.. _modeling-surfaces-index:
+.. _bpy.ops.surface:
 
-#############
-  Modifiers
-#############
+############
+  Surfaces
+############
 
 .. toctree::
    :maxdepth: 2
 
    introduction.rst
-   common_options.rst
-
-
-Modify
-======
-
-.. toctree::
-   :maxdepth: 1
-
-   modify/data_transfer.rst
-   modify/mesh_cache.rst
-   modify/mesh_sequence_cache.rst
-   modify/normal_edit.rst
-   modify/uv_project.rst
-   modify/uv_warp.rst
-   modify/weight_edit.rst
-   modify/weight_mix.rst
-   modify/weight_proximity.rst
-   modify/weighted_normal.rst
-
-
-Generate
-========
-
-.. toctree::
-   :maxdepth: 1
-
-   generate/array.rst
-   generate/bevel.rst
-   generate/booleans.rst
-   generate/build.rst
-   generate/decimate.rst
-   generate/edge_split.rst
-   generate/mask.rst
-   generate/mirror.rst
-   generate/multiresolution.rst
-   generate/remesh.rst
-   generate/screw.rst
-   generate/skin.rst
-   generate/solidify.rst
-   generate/subdivision_surface.rst
-   generate/triangulate.rst
-   generate/wireframe.rst
-
-
-Deform
-======
-
-.. toctree::
-   :maxdepth: 1
-
-   deform/armature.rst
-   deform/cast.rst
-   deform/corrective_smooth.rst
-   deform/curve.rst
-   deform/displace.rst
-   deform/hooks.rst
-   deform/laplacian_smooth.rst
-   deform/laplacian_deform.rst
-   deform/lattice.rst
-   deform/mesh_deform.rst
-   deform/shrinkwrap.rst
-   deform/simple_deform.rst
-   deform/smooth.rst
-   deform/surface_deform.rst
-   deform/warp.rst
-   deform/wave.rst
-
-
-Simulate
-========
-
-.. toctree::
-   :maxdepth: 1
-
-   simulate/explode.rst
-   simulate/ocean.rst
-   simulate/particle_instance.rst
+   toolbar/index.rst
+   structure.rst
+   primitives.rst
+   selecting.rst
+   editing/index.rst
+   properties/index.rst

introduction.rst.txt

@@ -3,163 +3,45 @@
 Introduction
 ************
 
-Modifiers are automatic operations that affect an object's geometry in a non-destructive way.
-With modifiers, you can perform many effects automatically that would otherwise be too tedious to do manually
-(such as subdivision surfaces) and without affecting the base geometry of your object.
+Curves are 2D objects, and surfaces are their 3D extension.
+Note however, that in Blender, you only have NURBS surfaces,
+no Bézier (you have the *Bézier* knot type, though; see below),
+nor polygonal (but for these, you have meshes!).
+Even though curves and surfaces share the same object type (with texts also...),
+they are not the same thing; for example,
+you cannot have in the same object both curves and surfaces.
 
-They work by changing how an object is displayed and rendered, but not the geometry which you can edit directly.
-You can add several modifiers to a single object to form `The Modifier Stack`_
-and *Apply* a modifier if you wish to make its changes permanent.
+.. _fig-surface-intro-surface:
 
-.. figure:: /images/modeling_modifiers_introduction_menu.png
+.. figure:: /images/modeling_surfaces_introduction_nurbs-surface.png
 
-   Modifiers menu.
+   NURBS surface in Edit Mode.
 
-They can be added to the active object using the *Add Modifier* drop-down menu at the top of their properties tab.
-New modifiers are always added at the bottom of the :ref:`stack <modifier-stack>` (i.e. will be applied last).
+As surfaces are 2D, they have two interpolation axes, U (as for curves) and V.
+It is important to understand that you can control the interpolation rules (knot, order, resolution)
+*independently* for each of these two dimensions
+(the U and V fields for all these settings, of course).
 
-There are four types of modifiers:
+You may ask yourself "but the surface appears to be 3D, why is it only 2D?".
+In order to be 3D, the object needs to have "Volume", and a surface, even when it is closed,
+does not have volume; it is infinitely thin.
+If it had a volume the surface would have a thickness (its third dimension). Hence,
+it is only a 2D object, and has only two interpolation dimensions or axes or coordinates
+(if you know a bit of math, think of non-Euclidean geometry -- well,
+surfaces are just non-Euclidean 2D planes...). To take a more "real-world" example,
+you can roll a sheet of paper to create a cylinder; well, even if it becomes a "volume",
+the sheet itself will remain a (nearly...) 2D object!
 
-Modify
-   These are tools similar to the *Deform* ones (see below),
-   however, they usually do not directly affect the geometry of the object,
-   but some other data, such as vertex groups.
-Generate
-   These are constructive/destructive tools that will affect the whole :term:`topology` of the mesh.
-   They can change the general appearance of the object, or add new geometry to it...
-Deform
-   Unlike *Generate* ones above, these only change the shape of an object, without altering its topology.
-Simulate
-   Those represent :doc:`physics simulations </physics/index>`. In most cases, they are automatically added to
-   the modifiers stack whenever a *Particle System* or *Physics* simulation is enabled. Their only role is to define
-   the position in the modifier stack from which is taken the base data for the simulation they represent.
-   As such, they typically have no attributes, and are controlled by settings exposed in
-   separate sections of the :doc:`Properties editor </editors/properties_editor>`.
+In fact, surfaces are very similar to the results you get when
+:doc:`extruding a curve </modeling/curves/properties/geometry>`.
 
 
-.. _bpy.types.Modifier.show:
+Visualization
+=============
 
-Interface
-=========
+There is nearly no difference from NURBS curves,
+except that the U direction is indicated by yellow grid lines,
+and the V one is materialized by pink grid lines, as you can see in
+Fig. :ref:`fig-surface-intro-surface`.
 
-.. _fig-modifiers-panel-layout:
-
-.. figure:: /images/modeling_modifiers_introduction_panel-layout.png
-
-   Panel layout (Subdivision Surface as an example).
-
-Each modifier's interface shares the same basic components, see Fig. :ref:`fig-modifiers-panel-layout`.
-
-At the top is the panel header.
-The icons each represent different settings for the modifier (left to right):
-
-Expand (down/right arrow icon)
-   Collapse modifier to show only the header and not its options.
-Type
-   An icon as a quick visual reference of the modifier's type.
-Name
-   Every modifier has a unique name per object. Two modifiers on one object must have unique names,
-   but two modifiers on different objects can have the same name. The default name is based off the modifier type.
-Render (camera icon)
-   Toggle visibility of the modifier's effect in the render.
-Show in viewport (screen icon)
-   Toggle visibility of the modifier's effect in the 3D View.
-Show in Edit Mode (vertices-square icon)
-   Display the modified geometry in Edit mode, as well as the original geometry which you can edit.
-Show on cage (vertices-triangle icon) -- Meshes only
-   Depends on the previous setting, if enabled, the modified geometry can also be edited directly,
-   instead of the original one.
-
-   .. warning::
-
-      While it shows edited items in their final, modified positions, you are still actually editing original data.
-      This can lead to weird and unpredictable effects with some tools,
-      and should be disabled whenever you need to perform complex or precise editing on the mesh.
-
-Apply On Spline Points (point-surface icon) -- Curves, Surfaces and Texts only
-   Apply the whole modifier stack up to and including that one on the curve or surface control points,
-   instead of their tessellated geometry.
-
-   .. note::
-
-      By default, curves, texts and surfaces are always converted to mesh-like geometry
-      before that the modifier stack is evaluated on them.
-
-Move (up/down arrow icon)
-   Move the modifier up/down in the stack.
-Delete (``X`` icon)
-   Delete the modifier.
-
-.. note::
-
-   The *Square*, *Triangle* and *Surface* icons may not be available, depending on the type of object and modifier.
-
-Below the header are three buttons:
-
-Apply
-   Makes the modifier "real": converts the object's geometry to match the applied modifier's results,
-   and deletes the modifier.
-Apply as Shape Key
-   Stores the result of that modifier in a new relative :doc:`shape key </animation/shape_keys/introduction>`.
-   This is only available with modifiers that do not affect the topology (typically, *Deform* modifiers only).
-
-   .. note::
-
-      Even though it should work with any geometry type that supports shape keys,
-      currently it will only work with meshes.
-
-Copy
-   Creates a duplicate of the modifier just below current one in the stack.
-
-.. warning::
-
-   Applying a modifier that is not first in the stack will ignore the stack order
-   (it will be applied as if it was the first one), and may produce undesired results.
-
-Below this header, all of the options unique to each modifier will be displayed.
-
-
-.. _modifier-stack:
-
-The Modifier Stack
-------------------
-
-Modifiers are a series of non-destructive operations which can be applied on top of an object's geometry.
-They can be applied in just about any order the user chooses.
-
-This kind of functionality is often referred to as a "modifier stack"
-and is also found in several other 3D applications.
-
-In a modifier stack the order in which modifiers are applied has an effect on the result.
-Fortunately modifiers can be rearranged easily by clicking the convenient up and down arrow icons.
-For example, the image below shows :doc:`Subdivision Surface </modeling/modifiers/generate/subdivision_surface>`
-and :doc:`Mirror </modeling/modifiers/generate/mirror>` modifiers that have switched places.
-
-.. list-table:: Modifier Stack example.
-
-   * - .. figure:: /images/modeling_modifiers_introduction_mirror-subdiv2.png
-          :width: 320px
-
-          The Mirror modifier is the last item in the stack and
-          the result looks like two surfaces.
-
-     - .. figure:: /images/modeling_modifiers_introduction_mirror-subdiv1.png
-          :width: 320px
-
-          The Subdivision surface modifier is the last
-          item in the stack and the result is a single merged surface.
-
-Modifiers are calculated from top to bottom in the stack.
-In this example, the desired result (on right) is achieved by first mirroring the object,
-and then calculating the subdivision surface.
-
-
-Example
-^^^^^^^
-
-.. figure:: /images/modeling_modifiers_introduction_stack-example-3.png
-
-   In this example a simple subdivided cube has been transformed into a rather complex object using
-   a stack of modifiers.
-
-`Download example file <https://wiki.blender.org/wiki/File:25-Manual-Modifiers-example.blend>`__.
+You can :ref:`hide and reveal <curves-show-hide>` control points just as with curves.

primitives.rst.txt

@@ -0,0 +1,70 @@
+.. _bpy.ops.surface.primitive*add:
+
+**********
+Primitives
+**********
+
+.. admonition:: Reference
+   :class: refbox
+
+   :Mode:      Object Mode and Edit Mode
+   :Menu:      :menuselection:`Add --> Curve`
+   :Hotkey:    :kbd:`Shift-A`
+
+.. seealso::
+
+   When adding curves there are some common options like other :ref:`Objects <object-common-options>`.
+
+In Object/Edit Mode, the *Add Surface* menu, provides six different surface primitives:
+
+.. list-table::
+
+   * - .. figure:: /images/modeling_surfaces_primitives_surface.png
+
+          NURBS surface primitives.
+
+     - .. figure:: /images/modeling_surfaces_primitives_curve.png
+
+          NURBS curve primitives.
+
+
+NURBS Curve
+===========
+
+*NURBS Curve* only have one control point on each V row.
+
+TODO.
+
+
+NURBS Circle
+============
+
+*NURBS Circle* only have one control point on each V row.
+
+TODO.
+
+Note how a circle :term:`NURBS` surface is never filled, unlike its "real" curve counterpart...
+
+
+NURBS Surface
+=============
+
+TODO.
+
+
+NURBS Cylinder
+==============
+
+TODO.
+
+
+NURBS Sphere
+============
+
+TODO.
+
+
+NURBS Torus
+===========
+
+TODO.

selecting.rst.txt

@@ -0,0 +1,196 @@
+
+*********
+Selecting
+*********
+
+This page discusses specific selecting tools for surface objects in Edit Mode.
+The Surface Edit more also uses the general select tools used which are described
+in the :doc:`interface section </interface/selecting>`.
+
+Surface selection in *Edit Mode* is very similar to
+:doc:`NURBS curve selection </modeling/curves/selecting>`.
+The basic tools are the same as with :doc:`meshes </modeling/meshes/selecting>`,
+so you can select a simple control point with an :kbd:`LMB`\ -click,
+add to current selection with :kbd:`Shift-LMB` clicks, :kbd:`B` order-select, and so on.
+
+
+Select Menu
+===========
+
+The *Select* menu (in the 3D Viewport header) is even simpler than for curves...
+
+All these options have the same meaning and behavior as in
+:doc:`Object Mode </scene_layout/object/selecting>`
+(and the specificities of *Box Select* in *Edit Mode* have already been discussed
+:doc:`here </modeling/meshes/selecting>`).
+
+All :kbd:`A`
+   Select all.
+None :kbd:`Alt-A`
+   Select none.
+Inverse :kbd:`Ctrl-I`
+   Selects all the geometry that are not selected, and deselect currently selected components.
+
+------------------------
+
+:ref:`Box Select <tool-select-box>` :kbd:`B`
+   Interactive box selection.
+:ref:`Circle Select <tool-select-circle>` :kbd:`C`
+   Interactive circle selection.
+
+------------------------
+
+`Select Random`_
+   Select random control points.
+
+`Checker Deselect`_
+   Select every Nth control point.
+
+`Select Linked`_ :kbd:`Ctrl-L`
+   Select control points that are connected to the current selection.
+
+`Select Similar`_ :kbd:`Shift-G`
+   Select control points that have similar properties to the current selection.
+
+------------------------
+
+`Select Control Point Row`_
+   Select a whole :ref:`row <modeling-surfaces-rows-grids>` of control points.
+
+------------------------
+
+`Select More/Less`_
+   Select objects based on their parent child relationships.
+
+
+Select Random
+=============
+
+.. admonition:: Reference
+   :class: refbox
+
+   :Mode:      Edit Mode
+   :Menu:      :menuselection:`Select --> Select Random`
+
+Select random control points.
+
+Percent
+   Selects the defined percentage of control points.
+Random Seed
+   :term:`Seed` used by the pseudo-random number generator.
+Action
+   Controls whether the operator *Selects* or *Deselects* control points.
+
+
+Checker Deselect
+================
+
+.. admonition:: Reference
+   :class: refbox
+
+   :Mode:      Edit Mode
+   :Menu:      :menuselection:`Select --> Checker Deselect`
+
+This tool applies an alternating selected/deselected checker pattern.
+This only works if you already have more than one control point selected.
+
+It works by changing the current selection so that only every Nth
+control points will remain selected, starting from the active one.
+
+Nth Selection
+   Skip every Nth element leaving it selected.
+Skip
+   Number of consecutive elements to skip (keep selected) at once.
+Offset
+   Offset from the starting point.
+
+
+Select Linked
+=============
+
+.. admonition:: Reference
+   :class: refbox
+
+   :Mode:      Edit Mode
+   :Menu:      :menuselection:`Select --> Select Linked`
+   :Hotkey:    :kbd:`L`, :kbd:`Ctrl-L`
+
+*Select Linked* will add to the selection the mouse cursor's nearest control point,
+and all the linked ones, i.e. all points belonging to the same surface.
+
+
+Select Similar
+==============
+
+.. admonition:: Reference
+   :class: refbox
+
+   :Mode:      Edit Mode
+   :Menu:      :menuselection:`Select --> Select Similar`
+   :Hotkey:    :kbd:`Shift-G`
+
+Selects control points that have certain similar properties to the active one.
+The :ref:`ui-undo-redo-adjust-last-operation` panel provides several selection options:
+
+Type
+   Type
+      Selects splines that have the same spline Type i.e. Bézier, NURBS or Poly.
+   Radius
+      Selects control points that have a similar Radius value.
+   Weight
+      Selects all points that have a similar Weight value.
+   Direction
+      Selects control points that have a similar handles direction.
+
+Compare
+   Equal, Greater, Less. (only for Radius, Weight) (ToDo 2.76)
+Threshold
+   Precision (ToDo 2.76)
+
+
+.. _bpy.ops.curve.select_row:
+
+Select Control Point Row
+========================
+
+.. admonition:: Reference
+   :class: refbox
+
+   :Mode:      Edit Mode
+   :Menu:      :menuselection:`Select --> Control Point Row`
+   :Hotkey:    :kbd:`Shift-R`
+
+This option works a bit like
+:ref:`edge loop selection <modeling-meshes-selecting-edge-loops>` for meshes,
+inasmuch it selects a whole :ref:`row <modeling-surfaces-rows-grids>` of control points,
+based on the active (the last selected) one. The first time you press :kbd:`Shift-R`,
+the V row passing through (containing) the active point will be added to the *current* selection.
+If you use again this shortcut, you will toggle between the U and V row of this point,
+removing *everything else* from the selection.
+
+
+Select More/Less
+================
+
+.. admonition:: Reference
+   :class: refbox
+
+   :Mode:      Edit Mode
+   :Menu:      :menuselection:`Select --> More/Less`
+   :Hotkey:    :kbd:`Ctrl-NumpadPlus` / :kbd:`Ctrl-NumpadMinus`
+
+Expand or contract the selection based on current selected control points.
+
+More
+   For each selected control point, select **all** its linked points (i.e. two, three or four).
+Less
+   For each selected control point, if **all** points linked to this point are selected, keep it selected.
+   For all other selected control points, deselect them.
+
+This implies two points:
+
+#. First, when **all** control points of a surface are selected, nothing will happen
+   (as for *Less*, all linked points are always selected, and of course, *More* cannot add any).
+   Conversely, the same goes when no control point is selected.
+#. Second, these tools will never "go outside" of a surface
+   (they will never "jump" to another surface in the same object).

structure.rst.txt

@@ -0,0 +1,97 @@
+
+*********
+Structure
+*********
+
+Many of the concepts from :doc:`curves </modeling/curves/introduction>`,
+especially :ref:`NURBS <curve-nurbs>` ones,
+carry directly over to NURBS surfaces,
+such as control points, *Order*, *Weight*, *Resolution*, etc.
+Here we will just talk about the differences.
+
+It is very important to understand the difference between NURBS curves and NURBS surfaces:
+the first one has one dimension, the latter has two.
+Blender internally treats NURBS surfaces and NURBS curves completely differently. There are
+several attributes that separate them but the most important is that a NURBS curve has
+a single interpolation axis (U) and a NURBS surface has two interpolation axes (U and V).
+
+However, you can have "2D" surfaces made of curves
+(using the :doc:`extrusion tools </modeling/curves/properties/geometry>`,
+or, to a lesser extent, the filling of closed 2D curves). And you can have "1D" curves made of surfaces,
+like a NURBS surface with only one row (either in U or V direction) of control points produces only a curve...
+
+Visually you can tell which is which by entering *Edit Mode* and looking at the 3D View header:
+either the header shows *Surface* or *Curve* as one of the menu choices. Also,
+you can :doc:`extrude </modeling/curves/properties/geometry>` a whole NURBS surface curve to create a surface,
+but you cannot with a simple NURBS curve.
+
+
+.. _modeling-surfaces-rows-grids:
+
+Control Points, Rows and Grid
+=============================
+
+Control points for NURBS surfaces are the same as for NURBS curves. However,
+their layout is quite constraining. The concept of "segment" disappears,
+replaced by "rows" and the overall "grid".
+
+A "row" is a set of control points forming one "line" in one interpolation direction
+(a bit similar to :ref:`edge loops <modeling-mesh-structure-edge-loops>` for meshes).
+So you have "U rows" and "V rows" in a NURBS surface.
+The key point is that *all* rows of a given type (U or V) have the *same* number of control points.
+Each control point belongs to exactly one U row and one V row.
+
+All this forms a "grid", or "cage", the shape of which controls the shape of the NURBS surface.
+A bit like a :doc:`lattice </animation/lattice>`...
+
+This is very important to grasp: you cannot add a single control point to a NURBS surface;
+you have to add a whole U or V row at once
+(in practice, you will usually use the Extrude tool, or perhaps the Duplicate one, to add those...),
+containing exactly the same number of points as the others. This also means that you will only
+be able to "merge" different pieces of surfaces if at least one of their rows matches together.
+
+
+.. _modeling-surfaces-weight:
+
+Weight
+======
+
+Similar to :ref:`NURBS Splines <curve-nurbs>` NURBS Surface control points have a weight property.
+This weight property controls how much influence the control point has on the surface.
+This weight should not be confused with the :ref:`Goal Weight <surface-goal-weight>`,
+which is used only for soft body simulations.
+The NURBS control point weight can be adjusted in the *W* number field of
+the :doc:`Transform panel </modeling/curves/editing/transform_panel>`.
+
+In Fig. :ref:`fig-surface-intro-weight` a single control point, labeled "C",
+has had its *Weight* set to 5.0 while all others are at their default of 1.0.
+As you can see, that control point *pulls* the surface towards it.
+
+.. _fig-surface-intro-weight:
+
+.. figure:: /images/modeling_surfaces_structure_weight.png
+
+   One control point with a weight of 5.
+
+.. note::
+
+   If all the control points have the same *Weight* then each effectively cancels each other out.
+   It is the difference in the weights that cause the surface to move
+   towards or away from a control point.
+
+
+Preset Weights
+--------------
+
+NURBS can create pure shapes such as circles, cylinders, and spheres
+(note that a Bézier circle is not a pure circle). To create pure circles, spheres,
+or cylinders, you must set to specific values the weights of the control points.
+This is not intuitive, and you should read more on NURBS before trying this.
+
+To create a sphere with 2D surfaces, its the same principle as with a 2D circle.
+You will note that the four different weights needed for creating a sphere
+(1.0, 0.707 = sqrt(0.5), 0.354 = sqrt(2)/4, and 0.25).
+
+.. figure:: /images/modeling_surfaces_structure_weight-sphere.png
+
+   A sphere surface.