Clarify parameter usage with `update_from_obj()` for zero-padding and similar functions

[PierreRaybaut]

Documentation: Clarify parameter usage with update_from_obj() for zero-padding and similar functions

Problem reported by user

A user reported confusion when trying to use zero-padding functionality in Sigima:

"I struggled a bit to define the parameters for zero-padding functions. I was trying to do zero-padding, but it only added one point. So I dug into your test code where I discovered update_from_object, which in hindsight seems obvious. I wasted a lot of time wondering if I was using the right functions because the parameter can be defined via sigima.proc.signal.ZeroPadding1DParam or sigima.proc.signal.fourier.ZeroPadding1DParam or sigima.params, etc. I kept questioning whether I was using the functions correctly and appropriately."

Summary of issues

1. update_from_obj() is not documented: When using strategies like "next_pow2", the parameter n (number of padding points) is computed dynamically based on the signal size. Without calling update_from_obj(signal), the default value of n=1 is used, resulting in only one point being added.

2. Multiple import locations cause confusion: The same parameter class can be imported from several locations:

   • sigima.params.ZeroPadding1DParam ✅ (recommended)
   • sigima.proc.signal.ZeroPadding1DParam ⚠️ (works but indirect)
   • sigima.proc.signal.fourier.ZeroPadding1DParam ⚠️ (internal module)

   This causes users to question whether they're using the correct class.

Solution

1. Enhanced ZeroPadding1DParam docstring

Added comprehensive documentation to the class docstring including:

• An "Important" admonition explaining that update_from_obj() must be called
• A complete code example showing the correct usage pattern
• Clear documentation of what each strategy does

2. New section in sigima.params module docstring

Added documentation explaining:

• Recommended import location (sigima.params)
• "Parameters Requiring Signal/Image Context" section explaining the update_from_obj() pattern
• Complete list of parameter classes that require update_from_obj()

3. New example: Zero Padding for FFT Enhancement

Created doc/examples/features/zero_padding.py demonstrating:

• The correct parameter creation and usage flow
• Before/after values of param.n to show the effect of update_from_obj()
• Different strategies and padding locations
• FFT comparison showing the benefit of zero-padding

Key code example (from new documentation)

import sigima.params
import sigima.proc.signal as sips

# Create the parameter object
param = sigima.params.ZeroPadding1DParam.create(strategy="next_pow2")

# ⚠️ At this point, param.n is still the default value (1)
# because the parameter doesn't know the signal size yet

# IMPORTANT: Update parameters from the signal
param.update_from_obj(signal)

# ✅ Now param.n is computed (e.g., 24 for a 1000-point signal)
result = sips.zero_padding(signal, param)

Parameter classes requiring update_from_obj()

For reference, the following parameter classes require calling update_from_obj():

• ZeroPadding1DParam: Computes n based on strategy and signal size
• ZeroPadding2DParam: Computes padding based on strategy and image size
• Resampling1DParam: Updates bounds based on signal range
• Resampling2DParam: Updates bounds based on signal range
• ResizeParam: Updates bounds based on image dimensions
• TranslateParam: Updates bounds based on image dimensions
• LineProfileParam: Updates line coordinates based on image dimensions
• BandPassFilterParam, BandStopFilterParam, HighPassFilterParam, LowPassFilterParam: Update frequency bounds

Files changed

• sigima/proc/signal/fourier.py: Enhanced ZeroPadding1DParam class docstring
• sigima/params.py: Added comprehensive section about parameter usage
• doc/examples/features/zero_padding.py: New example (auto-generates in documentation gallery)