---

name: model-building description: "Select and construct DLTK 0.2.1 TensorFlow 1.x 3D networks and core model-building blocks from explicit rank-5 tensor contracts." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

DLTK model building

Use this route when the task is to choose or instantiate a DLTK network, residual unit, activation, loss, metric, or 3D upsampling layer. This is an operating guide for the public DLTK 0.2.1 API; it assumes Python 3.7 with TensorFlow 1.15.0 and graph-mode APIs such as tf.Session, tf.layers, tf.contrib, and tf.estimator. Keep these legacy API calls unchanged unless a separate migration task is explicitly requested.

Route the request

• Classification or scalar regression: dltk.networks.regression_classification.resnet.resnet_3d.
• Dense multi-class segmentation: residual_unet_3d, asymmetric_residual_unet_3d, or residual_fcn_3d from dltk.networks.segmentation; choose UNet for concatenated skip features, asymmetric UNet for one decoder residual unit per scale, and FCN for additive upscore skips.
• Multi-scale segmentation experiment: deepmedic_3d, only with an explicit WIP acceptance; this implementation warns that it is not accuracy-equivalent to the original DeepMedic and uses linear/bilinear-style upsampling rather than the original repeat upsampling.
• Representation learning/reconstruction: convolutional_autoencoder_3d.
• GAN graph: dcgan_generator_3d and dcgan_discriminator_3d; the network functions only construct the generator/discriminator dictionaries, not a complete training loop.
• Resolution increase: simple_super_resolution_3d; its transpose-convolution output is only meaningful when the input is an intentionally downsampled low-resolution view of a target, not as evidence that arbitrary full-resolution data can be recovered.
• Reusable blocks: vanilla_residual_unit_3d, linear_upsample_3d, get_linear_upsampling_kernel, prelu, leaky_relu, dice_loss, sparse_balanced_crossentropy, and NumPy metrics. See api-reference.md and model-overview.md.

Construct safely

1. Confirm a TensorFlow 1.x graph and a static rank-5 input [batch, x, y, z, channels]. Network functions assert rank 5; channel count must be statically known for residual padding/conversion, flattening, and transpose-convolution output shapes.
2. Set num_classes, filters, and strides deliberately. For ResNet, UNet, FCN, autoencoder, and both GAN functions, len(filters) must equal len(strides). Each spatial stride is a 3-tuple. For a tiny graph, use all-one strides first; non-unit strides must leave compatible encoder/decoder spatial sizes and provide enough input extent for the chosen convolution/padding.
3. Pass mode=mode from the surrounding Estimator model_fn. Batch normalization uses training=(mode == tf.estimator.ModeKeys.TRAIN); TRAIN therefore requires the caller to run tf.GraphKeys.UPDATE_OPS under control dependencies. The network itself does not create the optimizer or EstimatorSpec.
4. Treat the returned dictionary as the public handoff. Segmentation and ResNet return logits, y_prob, and y_; the autoencoder and super-resolution networks return hidden_units/x_; the GAN generator returns gen, while the discriminator returns logits, probs, and pred. Preserve these keys when wiring prediction/export code.
5. For a real training workflow, hand feature/label shape and Reader concerns to data-pipelines, and hand Estimator loss/optimizer/update-op/export orchestration to training-and-estimators. Do not put file I/O or training loops in this route.
6. Run the bounded graph-only check when TensorFlow 1.15.0 is available: python scripts/network_smoke.py --family all from the model-building/ sub-skill directory The check creates tiny graphs and executes one forward pass; it never downloads data, trains, exports, or writes checkpoints. --help is safe in any working directory.

Loss and metric choices

• dice_loss(logits, labels, num_classes, smooth=1e-5, include_background=True, only_present=False) applies softmax internally and reduces Dice over batch/class spatial axes [1, 2, 3]; labels are sparse integer maps. only_present=True removes absent classes, and include_background=False removes class zero. It returns 1 - mean(Dice), not a per-class vector.
• sparse_balanced_crossentropy(logits, labels) expects sparse labels and inverse-frequency weights from the labels in the current tensor. A class absent from that tensor receives a stabilized weight; inspect batch composition before interpreting the value.
• dltk.core.metrics.dice, abs_vol_difference, and crossentropy are NumPy metrics. dice returns one value per class and may produce NaN for an absent class because its denominator is zero; crossentropy takes one-hot labels and interprets its first argument as logits unless logits=False.

Guardrails

• A rank-4 image or a missing channel dimension is not a valid network input. Fix the Reader/example shape to [B, X, Y, Z, C]; do not reshape labels into a fake channel merely to bypass an assertion.
• A len(filters) != len(strides) error means the architecture schedule is malformed. A concat/add shape error means cumulative encoder strides, input spatial dimensions, or skip branch sizes do not match; first use all-one strides, then introduce one spatial factor at a time.
• dcgan_discriminator_3d compares x > 0.5 on its logit tensor for pred; this is the package behavior, not a calibrated probability threshold. Use probs only when sigmoid probabilities are intended.
• deepmedic_3d is explicitly WIP and should not be presented as a reproduction of the original model or accuracy. Keep it out of routine smoke checks unless a task supplies compatible crop/pathway shapes.
• simple_super_resolution_3d performs learned transpose-convolution upsampling; the application workflow obtains a low-resolution input by artificial downsampling. It does not establish recovery of information absent from a genuinely low-resolution measurement.

For owned shape, mode, batch-normalization, output-key, and legacy-runtime failures, use troubleshooting.md. For complete verified signatures and family details, use api-reference.md and model-overview.md.