Release of version 1.0
SirVer
this thread should sum up the things we want to have in 1.0. As Robert
pointed out to me, we should use the time before having a release to
really stabilize the API.
Robert, maybe you could also sum up what you are working on in your
branch.
Cheers,
Holger
rjo
On Apr 1, 11:23 am, SirVer <sir...@gmx.de> wrote:
> Robert, maybe you could also sum up what you are working on in your
> branch.
See below for a changelog of the diff between me and trunk.
After a bit of testing it should be possible to merge the code as it
is not incompatible.
After that one can think about camera2.py, which is a partial rewrite
of camera.py. It's API is incompatible to camera.py.
It'd be great if someone could go through camera2.py and make some
remarks about choice of names, structure...
Best,
Robert.
* _dc1394core.py:
* some of the dictionaries for the enums in _dc1394core.py contain the
full name of the constant. bayer_method_vals["SOMETHING"] is more
concise than bayer_method_vals["BAYER_METHOD_SOMETHING"]. For those
dictionaries that did not already contain abbreviated enum names, I
added *_short dictionaries in parallel to the existing long ones.
* i added a DC1394Error, that is more specific than RuntimeError, can
be handled in all detail and knows about the function and error code
that resulted in it being raised
* i put the _fields_ of the structs into the class definition. thats a
bit more compact.
* i fixed the prototype of dc1394_format7_get_roi
* camera.py:
* Library: do not keep the cameralist as it becomes invalid as soon as
a camera is plugged or unplugged
* added a corrpution flag for Image()
* i factored the capture code such into dequeue/enqueue, image from
frame creation, and setup teardown of the capture state
(start,stop)_(capture,video,one_shot,multi_shot) so that one can also
use the dc1394 api in a synchronous threadless and direkt fashion.
* no special treatment for "shutter" ms versus s
* added power() methods for the camera
* added flush() method to flush pending frames()
* the thing with TRIGGER_ACTIVE_* 704/705 versus 0/1 seems really
serious. my libdc1394 and my pointgrey cams use 704/705.
* camera2.py, the big hunk:
* its a rewrite of camera.py (with some copy paste)
* use property decorators
* kept to one pydc1394 method per dc1394 function to not exclude any
way of excercising the full dc1394 api by design
* tried to keep the dc1394 names where possuble (_is_switchable ->
switchable...), do not abbreviate where possible
* let dc1394 or the objects do all error handling, no explicit error
generation needed
* allow for switching between absolute and non-absolute control,
* add a setup() method to Feature to set the most commonly changed
properties with one call
* implemented Trigger, Temperature, Whitebalance, Whiteshading as
Feature-subclasses, as they need different handling than the generic
features but one does not want trigger-methods on non-trigger features
* video modes implemented as objects, such that you can assign them
directly (cam.mode = mode) and program format7 parameters as
attributes on them (cam.mode = my_format7_mode, cam.mode.size =
(200,300)...)
* Camera() takes the first camera in by default (creates and maintains
the library by itself)
* add a setup() method to camera to change multiple features in one
call
* add all format7 methods
* added memory_save, load
* allow for polling capture mode
* add strobe register functions
* add fileno() to integrate the camera into select()-based access
* dc1394_get/set_framerate is "rate" as "framerate" is a feature
* ctypes.ARRAY+numpy.frombuffer is faster than (c_char*size)
+numpy.fromstring but does not copy the data. the image data becomes
invalid as soon as we enqueue() the frame again. that means that we
either have to copy the data on image creation or enqueue the frame
only if the image data is released by the user (which seems hard),
* automatic endianess detection from the frame, datadepth, videomode
as attributes of the frame.
* synchronous access exercising only the dc1394 api at the moment.
I'll add the threaded acquisition again.
* docstrings are missing but coming soon
* i added setuptools before distutils so one could profit from their
nice features (i especially like "setup.py develop"). distutils is
still the fallback.
* examples/emva1288.py: an attempt to perform EMVA1288 style tests and
measurements on the cameras. it's partially specific to pointgrey
cameras at the moment but could easily be extended/adapted,
determines, dark current, dark counts, system gain etc..
* examples/dc1394.py: some test script for trigger_mode_14, strobe
etc. for pointgrey cameras
Tomio
Hi All,
This list of Robert inspired me to add some comments.
1. what about a working 0.8 release? Would that be an option?
2. some comments:
> * i fixed the prototype of dc1394_format7_get_roi
Thanks 8).
> * camera.py:
> * Library: do not keep the cameralist as it becomes invalid as soon as
> a camera is plugged or unplugged
Would it be better making a getter for this, so the list is always
actual? Then this can call the enumerate, and the user does not have
to worry about it.
> * added a corrpution flag for Image()
One general idea behind the capture thread, as I understand it, is to
make the capture as fast as possible. Should this feature be moved to
the Image class then, or is it a really fast function not interferring
with the capture speed?
> * i factored the capture code such into dequeue/enqueue, image from
> frame creation, and setup teardown of the capture state
> (start,stop)_(capture,video,one_shot,multi_shot) so that one can also
> use the dc1394 api in a synchronous threadless and direkt fashion.
This is definitely a clean way of groupping.
> * no special treatment for "shutter" ms versus s
> * added power() methods for the camera
> * added flush() method to flush pending frames()
That means the lib is more complete.
> * the thing with TRIGGER_ACTIVE_* 704/705 versus 0/1 seems really
> serious. my libdc1394 and my pointgrey cams use 704/705.
I will double check our cams.
Perhaps we should implement both. If the camera retuns a value of 704
or 705 for a query, add 704 to the keys. Or redefine the dicts, they
are short fortunately.
> * camera2.py, the big hunk:
perhaps it would be cleaner to go through what we are doing and why.
I can only speak for myself: for me, the aim of the game is not a
complete copy of the dc1394, but a functional python wrapper, which
provides a comfortable access to all the camera features, proper
warnings/errors about problems and speed.
As far as I see it, the current state is quite close. So, we should
perhaps come up with what is missing, what is wrong and why.
For example:
- Image: a child of ndarray inheriting features of the camera frame,
including conversion functions. (It may have a danger of weird arrays
for Bayern encodings and YUV formats.)
- Camera class: descriptor of an opened camera, including all features
and functionality
- CameraProperty: a subclass to describe a feature of the camera (this
may be better separated according to the feature, because special
features, such a trigger may have properties the others do not have)
- acquisition is available in a separate thread for fast aquisition ->
disk streaming (?)
- ... wishlist..., special cameras...
These were my dime at the moment.
Best regards,
Tamas
rjo
> 1. what about a working 0.8 release? Would that be an option?
To me the term "1.0 release" doesn't mean anything anyway. ;-)
> > * Library: do not keep the cameralist as it becomes invalid as soon as
> > a camera is plugged or unplugged
>
> Would it be better making a getter for this, so the list is always
> actual? Then this can call the enumerate, and the user does not have
> to worry about it.
yes. camera2.py has that.
> > * added a corrpution flag for Image()
>
> One general idea behind the capture thread, as I understand it, is to
> make the capture as fast as possible. Should this feature be moved to
> the Image class then, or is it a really fast function not interferring
> with the capture speed?
Well. I must admit that I don't see how a "capture thread" can help
gain speed. The thread just shovels all frames into a queue. There
seems to be no conceptual difference to the DMA buffer itself (which
can also be chosen large). In the other case where only the most
recent frame is kept, I see the need for a thread only if the
application is ill-designed and blocks to long on other tasks.
For the corruption flag: I'd speculate that it involves some
computation (maybe a checksum). And it only works as long as the
original frame is available. In camera2.py (where frames initially
maintain a reference to the DMA frame) it's a proprty of the frame.
> > * the thing with TRIGGER_ACTIVE_* 704/705 versus 0/1 seems really
> > serious. my libdc1394 and my pointgrey cams use 704/705.
>
> I will double check our cams.
> Perhaps we should implement both. If the camera retuns a value of 704
> or 705 for a query, add 704 to the keys. Or redefine the dicts, they
> are short fortunately.
Sure. But the setter (and it's dictionary) can not be fixed like that.
> > * camera2.py, the big hunk:
>
> perhaps it would be cleaner to go through what we are doing and why.
Yes.
> I can only speak for myself: for me, the aim of the game is not a
> complete copy of the dc1394, but a functional python wrapper, which
> provides a comfortable access to all the camera features, proper
> warnings/errors about problems and speed.
Agreed.
A broad coverage of dc1394 (ultimately leading to completeness) is
undoubtedly an attractive feature.
> As far as I see it, the current state is quite close. So, we should
> perhaps come up with what is missing, what is wrong and why.
Yes. In general if I look at camera.py I have the feeling that the
code is trying to out-smart the user. Like printing warnings and doing
nothing or adding unnecessarly complex special case handling where a
the alternative would be just calling upon dc1394 functions to fail.
The latter would be much more helpful and less error-prone. I tried to
fix that and ended up with camera2.py...
> For example:
> - Image: a child of ndarray inheriting features of the camera frame,
> including conversion functions. (It may have a danger of weird arrays
> for Bayern encodings and YUV formats.)
Camera class: descriptor of an opened camera, including all features
> and functionality
All agreed.
> - CameraProperty: a subclass to describe a feature of the camera (this
Why not call it "Feature" then?
> may be better separated according to the feature, because special
> features, such a trigger may have properties the others do not have)
Yes. The four special non-generic features (temperature, trigger,
whitebalance, whiteshading) are handled in subclasses in camera2.py
> - acquisition is available in a separate thread for fast aquisition ->
> disk streaming (?)
How can that be helpful? See above.
Greetings,
Robert.
Tomio
A general note: camera2.py is a nice rewrite from scratch. But then
there is a question: do we fix camera.py, or start over? (Is there a
user base already to get upset by a start over? Is there compatibility
to be kept?)
Release: numbers under 1.0 mean it is a work in progress. Usually 1.0
is the stable milestone people can build upon. But sometimes this is
not kept either 8).
Threading: not needed, but sometimes useful. In research we time to
time run into high speed dumping of data to a harddisk. For
microfluidics I need sometimes 100 frames/sec with sg. like 480x640
resolution. This is no problem, but any sitting around of the software
may block it. If I want to keep some feedback to the user, than such
recording should not be blocking for the user, so the user may stop
recording, and receive some frames to the screen as well. In such
cases threading is useful. (The blocking way was already achieved by
my old C API wrapper lib last year.)
We agree, that the Camera class should provide all functionality, then
the thread is an option we provide for the comfort of the end user/
developer.
Corruption flag:
The frame has to be still dequeued, which means this infor has to be
retrieved right after the image, that one can release the ring buffer.
Trigger: the camera init can have a look at the trigger polarity value
and set a flag for this. The getter/setter can then use that, and it
shall be camera independent.
Back to some general questions:
There are things we can comfortably hide from the end user, and ones
we should not. But which to keep visible with errors and which to make
comfortable, we have to decide.
I am not a programmer and there may be quite a couple of folks out
there who appreciate simplicity when using the lib. This is one reason
why I prefer the feature setting for example taking care of Format7
things under the same umbrella as the other features.
What I mean, for example, shooting images with start(), shot(), stop()
is simple. With set_flags..., start(), dequeue(), copy(), enqueue(),
stop() is getting a bit complicated, which we comfortably can hide
with providing flags to the start() function...
The separate classes for the special features are a good idea, they
make things easier, just the Camera.__init__ has to take care of them.
This may keep things cleaner when one reads the code.
CameraProperties: why not Features? Falls back to my first question. I
would love to see the opinion of Holger on this as well.
So much for now.
Best regards,
Tamas
SirVer
sorry for the late reply and not having reviewed both your codes
yet :/. Times are a bit crazy atm.
> A general note: camera2.py is a nice rewrite from scratch. But then
> there is a question: do we fix camera.py, or start over? (Is there a
> user base already to get upset by a start over? Is there compatibility
> to be kept?)
compatibility. We can do whatever we want with the lib at this state.
As soon as a 1.0 version is release we pretty much have to stick with
the API.
> Threading: not needed, but sometimes useful. In research we time to
> time run into high speed dumping of data to a harddisk. For
> microfluidics I need sometimes 100 frames/sec with sg. like 480x640
> resolution. This is no problem, but any sitting around of the software
> may block it. If I want to keep some feedback to the user, than such
> recording should not be blocking for the user, so the user may stop
> recording, and receive some frames to the screen as well. In such
> cases threading is useful. (The blocking way was already achieved by
> my old C API wrapper lib last year.)
to make use of more CPUs, but to do this in Python we have to respect
the GIL and we would have to use the multiprocessing package.
Nevertheless, making threading the default allows to have blocking
while also allowing none blocking IO. I see no reason to throw the
threading approach at this point in time.
>
> We agree, that the Camera class should provide all functionality, then
> the thread is an option we provide for the comfort of the end user/
> developer.
> I am not a programmer and there may be quite a couple of folks out
> there who appreciate simplicity when using the lib. This is one reason
> why I prefer the feature setting for example taking care of Format7
> things under the same umbrella as the other features.
as well. I agree that making things simple should be prime. That's why
I also included UI code into pydc1394 which was well received so far.
> The separate classes for the special features are a good idea, they
> make things easier, just the Camera.__init__ has to take care of them.
> This may keep things cleaner when one reads the code.
> CameraProperties: why not Features? Falls back to my first question. I
> would love to see the opinion of Holger on this as well.
property. cam.shutter = <time in ms> was my intention. But since the
values hold more informations like range and raw values, I decided for
a watered down (or enhanced?) property approach were the actual value
must be set via cam.shutter.val = <time in ms>. I think the name
Property makes sense for things that most/all cameras have: shutter,
framerate, mode. I think Trigger is a feature of a camera, but since
every feature is a property in my understanding, I'd say to stick with
CamProperty instead of Feature.
I am currently reluctant to do big changes to the code base as I am
afraid of breaking/regressing things. A good feature to add to a 1.0
release would be a bigger test suite that plays well with all cameras
and only tests the feature the attached camera has. Otherwise we can
never be sure that some changes do not break anything. Someone up for
this?
Cheers,
Holger
--
Subscription settings: http://groups.google.com/group/pydc1394/subscribe?hl=de
Tomio
It would be great to see the next merged trunk, and then summarize
what we need to do.
What kind of test have you thought about? I have never tried the
python testing system, but some code which walks through the features
and tries them setting/getting on a camera should be no problem.
One can use the setattr()/getattr() system, but it may be better doing
more specifically for the various properties. Temperature is normally
ON/OFF only, trigger, trigger modes, can be listed, polarity as well,
shutter values can be set etc.
Would it be setting up some ideal parameters, or just set them around,
such as sending them to the end of their ranges, then back to original
simply to test the functions work...
What do you think?
Tomio
SirVer
> It would be great to see the next merged trunk, and then summarize
> what we need to do.
really, because essential your changes and jordens interfere pretty
much. Also that there is now a camera2.py which essentially replaces
camera.py makes it really hard to get one feature from left to right
and back.
> What kind of test have you thought about? I have never tried the
> python testing system, but some code which walks through the features
> and tries them setting/getting on a camera should be no problem.
capable off, then running all feature tests the camera can support.
This makes bug tracking so much easier.
> One can use the setattr()/getattr() system, but it may be better doing
> more specifically for the various properties. Temperature is normally
> ON/OFF only, trigger, trigger modes, can be listed, polarity as well,
> shutter values can be set etc.
> Would it be setting up some ideal parameters, or just set them around,
> such as sending them to the end of their ranges, then back to original
> simply to test the functions work...
anyways manually: so just what you propose, from trivial, to very
simple and some advanced use cases. The current examples directory is
essentially packed with tests.
Cheers,
Holger