Hello all,

I have a question and would appreciate your help.

While reading 'What's New in Csound 7’, I found an interesting example of Hilbert transform using the new Complex Type.
So I wanted to try another Hilbert transform example described in the SciPy.signal manual [1].
In that example, phase unwrapping is used, and Csound has an opcode for it. However I became confused when reading the Csound manual:

unwrap
Applies a unwrapping operation to a vector of phase values stored in an array.
The output is an array with phases in the range of [-pi, pi).

To me, this sounds like wrapping rather than unwrapping. I tested the unwrap opcode, and it indeed wraps the signal in the range of [-pi, pi).
Is my understanding wrong, or is there something wrong in the wrap opcode?

[1] https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.hilbert.html

Regards,
Tetsuya Miwa
Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

That's what it does yes. 

Prof. Victor Lazzarini
Maynooth University
Ireland

> On 4 Dec 2025, at 16:11, Tetsuya Miwa  wrote:
> 
> Hello all,
> 
> I have a question and would appreciate your help.
> 
> While reading 'What's New in Csound 7’, I found an interesting example of Hilbert transform using the new Complex Type.
> So I wanted to try another Hilbert transform example described in the SciPy.signal manual [1].
> In that example, phase unwrapping is used, and Csound has an opcode for it. However I became confused when reading the Csound manual:
> 
> unwrap
> Applies a unwrapping operation to a vector of phase values stored in an array.
> The output is an array with phases in the range of [-pi, pi).
> 
> To me, this sounds like wrapping rather than unwrapping. I tested the unwrap opcode, and it indeed wraps the signal in the range of [-pi, pi).
> Is my understanding wrong, or is there something wrong in the wrap opcode?
> 
> [1] https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.hilbert.html
> 
> Regards,
> Tetsuya Miwa
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>        https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here

Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

and yes, it seems the opposite to the rest of the world. My apologies. One way to improve it is to add an optional parameter to set it to "unwrap" mode in the most accepted sense of the word. So it could perform either function.

Prof. Victor Lazzarini
Maynooth University
Ireland

> On 4 Dec 2025, at 16:11, Tetsuya Miwa  wrote:
> 
> Hello all,
> 
> I have a question and would appreciate your help.
> 
> While reading 'What's New in Csound 7’, I found an interesting example of Hilbert transform using the new Complex Type.
> So I wanted to try another Hilbert transform example described in the SciPy.signal manual [1].
> In that example, phase unwrapping is used, and Csound has an opcode for it. However I became confused when reading the Csound manual:
> 
> unwrap
> Applies a unwrapping operation to a vector of phase values stored in an array.
> The output is an array with phases in the range of [-pi, pi).
> 
> To me, this sounds like wrapping rather than unwrapping. I tested the unwrap opcode, and it indeed wraps the signal in the range of [-pi, pi).
> Is my understanding wrong, or is there something wrong in the wrap opcode?
> 
> [1] https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.hilbert.html
> 
> Regards,
> Tetsuya Miwa
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>        https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here

Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

Thank you for your comment, Victor.
After rereading ’The audio programming book’, I think I finally managed to understand why the unwrap opcode actually ”unwraps”.
The following two methods return the same result:
  Calculate atan2 -> “unwrap" phase -> calculate phase difference
  Calculate atan2 -> calculate phase difference -> bring the difference to the -pi to pi range (=the logic of unwrap opcode)

I don’t think updating unwrap opcode is necessarily required. It is ten years old and no one has ever commented on this before...
It might be a good idea to update the manual, though it would be difficult for me to handle with my current knowledge.

Tetsuya Miwa

> 2025/12/05 16:03、vlz のメール:
> 
> and yes, it seems the opposite to the rest of the world. My apologies. One way to improve it is to add an optional parameter to set it to "unwrap" mode in the most accepted sense of the word. So it could perform either function.
> 
> Prof. Victor Lazzarini
> Maynooth University
> Ireland
> 
>> On 4 Dec 2025, at 16:11, Tetsuya Miwa  wrote:
>> 
>> Hello all,
>> 
>> I have a question and would appreciate your help.
>> 
>> While reading 'What's New in Csound 7’, I found an interesting example of Hilbert transform using the new Complex Type.
>> So I wanted to try another Hilbert transform example described in the SciPy.signal manual [1].
>> In that example, phase unwrapping is used, and Csound has an opcode for it. However I became confused when reading the Csound manual:
>> 
>> unwrap
>> Applies a unwrapping operation to a vector of phase values stored in an array.
>> The output is an array with phases in the range of [-pi, pi).
>> 
>> To me, this sounds like wrapping rather than unwrapping. I tested the unwrap opcode, and it indeed wraps the signal in the range of [-pi, pi).
>> Is my understanding wrong, or is there something wrong in the wrap opcode?
>> 
>> [1] https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.hilbert.html
>> 
>> Regards,
>> Tetsuya Miwa
>> Csound mailing list
>> Csound@listserv.heanet.ie
>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>> Send bugs reports to
>>       https://github.com/csound/csound/issues
>> Discussions of bugs and features can be posted here
> 
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>        https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here

Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here

Thanks, I have a PR out now for that update, which may be useful at least for putting the opcode in line with SciPy.


Prof. Victor Lazzarini
Maynooth University
Ireland

> On 6 Dec 2025, at 11:18, Tetsuya Miwa  wrote:
> 
> Thank you for your comment, Victor.
> After rereading ’The audio programming book’, I think I finally managed to understand why the unwrap opcode actually ”unwraps”.
> The following two methods return the same result:
>  Calculate atan2 -> “unwrap" phase -> calculate phase difference
>  Calculate atan2 -> calculate phase difference -> bring the difference to the -pi to pi range (=the logic of unwrap opcode)
> 
> I don’t think updating unwrap opcode is necessarily required. It is ten years old and no one has ever commented on this before...
> It might be a good idea to update the manual, though it would be difficult for me to handle with my current knowledge.
> 
> Tetsuya Miwa
> 
>> 2025/12/05 16:03、vlz のメール:
>> 
>> and yes, it seems the opposite to the rest of the world. My apologies. One way to improve it is to add an optional parameter to set it to "unwrap" mode in the most accepted sense of the word. So it could perform either function.
>> 
>> Prof. Victor Lazzarini
>> Maynooth University
>> Ireland
>> 
>>>> On 4 Dec 2025, at 16:11, Tetsuya Miwa  wrote:
>>> 
>>> Hello all,
>>> 
>>> I have a question and would appreciate your help.
>>> 
>>> While reading 'What's New in Csound 7’, I found an interesting example of Hilbert transform using the new Complex Type.
>>> So I wanted to try another Hilbert transform example described in the SciPy.signal manual [1].
>>> In that example, phase unwrapping is used, and Csound has an opcode for it. However I became confused when reading the Csound manual:
>>> 
>>> unwrap
>>> Applies a unwrapping operation to a vector of phase values stored in an array.
>>> The output is an array with phases in the range of [-pi, pi).
>>> 
>>> To me, this sounds like wrapping rather than unwrapping. I tested the unwrap opcode, and it indeed wraps the signal in the range of [-pi, pi).
>>> Is my understanding wrong, or is there something wrong in the wrap opcode?
>>> 
>>> [1] https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.hilbert.html
>>> 
>>> Regards,
>>> Tetsuya Miwa
>>> Csound mailing list
>>> Csound@listserv.heanet.ie
>>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>>> Send bugs reports to
>>>      https://github.com/csound/csound/issues
>>> Discussions of bugs and features can be posted here
>> 
>> Csound mailing list
>> Csound@listserv.heanet.ie
>> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
>> Send bugs reports to
>>       https://github.com/csound/csound/issues
>> Discussions of bugs and features can be posted here
> 
> Csound mailing list
> Csound@listserv.heanet.ie
> https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
> Send bugs reports to
>        https://github.com/csound/csound/issues
> Discussions of bugs and features can be posted here

Csound mailing list
Csound@listserv.heanet.ie
https://listserv.heanet.ie/cgi-bin/wa?A0=CSOUND
Send bugs reports to
        https://github.com/csound/csound/issues
Discussions of bugs and features can be posted here